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Restricted Distribution 



os$allocate_obJect 

( 

IN objectjd : e$objectJd; 
IN allocationjd : e$object_id; 
) RETURNS status; 



DESCRIPTION 



The os$allocate_object service allocates the specified object to the specified 
allocation object. An allocation object can be a thread, process, job, user, or 
identifier object. 

Each allocation object defines an allocation class. An allocation class is the 
set of thi^ads that can access an object allocated to an allocation object. 
If an object is allocated and a thread is a member of the allocation class 
defined by the allocation object, the thread can access the object (assuming 
the object access check performed after the allocation check is successful). 

The allocation classes defined for each allocation object are: 

thread object - The only member of the thread object edlocation class is the 
thread of the thread object that an object is allocated to. 

process object - The members of the process object allocation class are the 
threads of the process object that an object is allocated to and the threads 
of any child process of the process object that an object is allocated to. 

job object - The members of the job object allocation class are the threads 
of the job object that an object is allocated to. 

user object - The members of the user object allocation class are the 
threads owned by the user who is represented by the user object. An 
object is allocated to the user object. 

identifier object - The members of the identifier object allocation class are 
the threads that hold the identifier represented by the identifier object. 

When an allocation object is deleted, any objects allocated to the object are 
automatically deallocated. 

The -visibility of an object determines the allocation objects to which an 
object can be allocated. 

- If the object is at the system level, the object can be allocated to any 
allocation object. 

- If the object is at the job level, the object can be allocated to the job, 
process, and thread allocation objects. 

- If the object is at the process level, the object can be allocated to the 
process and thread allocation objects. 



ARGUMENTS 



object_id 

Supplies the object id of the object to allocate. 
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allocation_id 

Supplies the object id of the allocation object to which the specified object 
is allocated. 



RETURN 

WAillCC status$_normal normal, successful completion. 

status$_invalid_objectJd invalid object id. 

status$_invalid_allocationJd invalid allocation id. 

status$_object_type_ the object identified by Xhe allocation id is not an 

mismatch allocation object. 

status$_object_alraady_alloc object is already allocated. 

status$_different_alloc_class the calling thread is not a member of the allocation 

object's allocation class. 

status$Jnvalid_visibility the object cannot be allocated because the visibility 

of the object prevents it from iseing allocated to the 
specified allocation object. 
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Restricted Distribution 



os$create container 



( 



OUT containerjd : e$obJect_id; 

IN object_parameters : e$object_j)arameters = DEFAULT; 

) RETURNS STATUS; 



DESCRIPTION 



The os$create_container service creates a container. Any type of object 
except containers and container directories can be inserted into this type 
of object container. 

If the object container id value is specified in the object psirameters record, 
it must identify a container directory. A container can only be inserted 
into a container directory. 



ARGUMENTS 



containerjd 

Returns the object id of the created container. 

object_parameters 

SuppUes the object container in v?hich the object is inserted, the name of 
the object, and the access control list (ACL) of the object. If this argument 
is not suppUed or if it is supplied but not all values in the object parameter 
record are supplied, the service applies default values. The default object 
container is the process container directory, the default name is none, and 
the default ACL is none. 



RETURN 
VALUES 



status$_normal 

status$Jnvalid_object_id 

status$_object_type_ 
mismatch 

status$_invalid_object 

status$_dupiicate_object 

status$_quota_exceeded 



status$_object_container_f u II 



normal, successful completion. 

the object id of Mhe object container is invalid. 

the object specified by the object Container id was 
not a container directory. 

the object to insert is not a container. 

a container having the same type, mode and name 
was found. 

the caller does not have enough quota for the 
specified container or for an expanded container 
directory. 

the container directory is full. 
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os$create_identifier 

( 

OUT identifierjd : e$object_id; 

IN object_parameters : e$object_parameters; 

IN Identifier : e$identifier; 

) RETURNS status; 



DESCRIPTION 



The os$create_id.entifier service creates an identifier object. An identifier 
object is an allocation object that represents a valid identifier defined on 
the system. Because it is an allocation object, objects can be allocated 
to the identifier object. Any thread that is a holder of the identifier 
represented by the identifier object can access any objects allocated to the 
identifi.er object. 

To create an identifier object, the caller must hold the identifier that the 
identifier object is to represent. 

The identifier object is inserted in the exec$identifier_container system 
level container. The name of the object is the alphanumeric name of the 
identifier the object represents. 



ARGUMENTS 



identifier_id 

Returns the object id of the created identifier object. 

obJect_parameters 

SuppUes the object container in which the object is inserted, the name of 
the object, and the access control list (ACL) of the object. The values for 
the name and object container are ignored. If a value for the ACL is not 
supplied, the default is 

None. 

i V 

identifier - Supplies the identifier that the identifier object represents. 



RETURN 
VALUES 



status$_normal 
status$_invalidjdentifier 
status$_ciu pi i cate_o bject 



normal, successful completion. 

the caller is not a holder of the specified identifier. 

duplicate object found in object container. 
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os$create__reference_id 

( 

IN objectjd ; e$object_icl; 

IN contalnerjd : e$objectJd = DEFAULT; 

OUT referencejd : e$objectJd; 

) RETURNS status; 



DESCRIPTION 



The os$create_reference_id service creates a reference id to an object. A 
reference id ensures that as long as the reference id exists, the object 
cannot be deleted. 

A reference id C£in only be created for objects whose principal id still exists. 

The container through which the reference id identifies the object must be 
at a less visible level than the principal object id's container. 

A reference id cannot be created for an object that does not allow reference 
ids. For example, container directories and containers do not sdlow 
reference ids. 



ARGUMENTS 



objectjd 

Supplies the object id of the object that a reference id is created for. 

containerjd 

SuppUes the container id of the container thru which the object is 
referenced. 

refere/7ce_/d 

Returns the reference id. 



RETURN 
VALUES 



status$_normal 

status$Jnvalid_objectJd 

status$Jnvalicl_containerJd 

status$_object_typ8_ 
mismatch 

status$_rsfBrence_not_ 
allowed 

status$_invalid_targetjevel 



normal, successful completion. 

invalid object id. 

invalid container id. 

the object type of the specified container was not a 
container. 

the object does not allow reference ids. 

the level of the container is not more visible than the 
object's container. 
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os$deallocate_object 



( 

IN objectjd : e$objectJd; 
) RETURNS STATUS; 



QESCRiPTION Th® os$deallocate_object service deallocates the spedfied object. 

The caller must be a member of the allocation object's allocation class in 
order to deallocate the object. 



ARGUMENTS 



objectjd 

SuppUes the object id of the object to deallocate. 



RETURN 
VALUES 



status$_nprmal normal, successful completion. 

status$_invalid_objactJd invalid object id. 

status$_object_not_allocated object not allocated. 
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os$delete_objectJd 



( 

IN objectjd : e$object_id; 
) RETURNS STATUS; 



DESCRIPTION 



The os$delete_object_id service deletes the object id of the specified object. 
When all object ids that identify the object have been deleted, the object is 
no longer accessible. 

Paged or nonpaged pool quota is returned to the correct level when the 
object id is deleted. If the object identified by the deleted object id was at 
the system level, no quota is returned. 

If the object id count decrements to 0, the remove object service 
routine specified by the object's OTD is called. After the remove object 
service routine returns, this service dereferences the object by calling 
obj$dereference_object. 



ARGUMENTS 



objectjd 

Supplies the object id to delete. 



RETURN 
VALUES 



status$_normal 
status$Jnvalid_objectJd 



nortnal, successful completion, 
invalid object id. 
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os$delete_object_name 

( 

IN objectjd : e$objectJd; 
) RETURNS status; 



DESCRIPTION The os$delete_object_name service deletes the specified object's naine and 

removes the name from the object container's object name table. 



ARGUMENTS objectjd 

SuppUes the object id of the object whose name is deleted. 



RETURN 
VALUES 



status$_normal 

status$Jnvalid_objeot_id 

status$_name_already_ 
deleted 



normal, successful completion. 

invalid object id. 

the object name of the object was already deleted. 
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os$get_objconJnformation 

( 

IN objectjcontainerjd : e$objectJd; 
INitemJist : POINTER e$item_llst_type; 
) RETURNS status; 

DESCRIPTION 1^® os$get_objconL_information service returns the object ids of objects 

in the object container and the logical names in the object contsdners' 
logical name table. An object container is either a container directory or 
container. 

Object ids are returned in the e$c_object_id_Ust item. This item is of type 
e$object_id_hst. The e$object_id_list type is made up of the foUovring 
fields: 

- length - This field is set by the caller and indicates to the service the 
number of entries in the object_id field. 

- last_valid_entry - This field is set by the service and indicates to the 
caller the last entry in the object_id field that contains a vahd value. 

- context - This field maintains context across multiple calls to the service. 
It is set by the caller and the service. 

- object_id - This field is set by the service and indicates to the caller the 
object ids that identify objects in the object container. 

As described above, the last_valid^entry field indicates the last entry in 
the oljiect_id field that contains a vahd value. This field can have the 
follomng values: 

- If the value of this field is zero, the service did not return any object ids. 
This means the object container does not hold any objects. A subsequent 
call to the service would not return additional object ids. 

- If the value is non-zero and is less than the maximum number of entries, 
the service returned the object ids that identify all the objects in the object 
container. A subsequent call to the service would not return additional 
object ids. 

- If the value is non-zero and is equal to the maximum number of entries, 
the service may have returned the object ids that identify all the objects 
in the object container. The caller must examine the status returned by 
the service to determine if all the object ids were returned. If the status 
returned was status$_no_more_info, the service returned all the object ids 
and a subsequent call to the service would not return additional object ids. 
If the status returned was status$_normal, the service did not return all 
the object ids and a subsequent call to the service might return additional 
object ids. 

Note that the service might return additional object ids. At the time the 
call completed, the service may have found more objects and therefore 
more object ids than could be returned. Between the time the first call 
completes and a subsequent call is made, the objects could be deleted. The 
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subsequent call would then return a status of status$_no_more_info and 
the laist_vaUd_entry field would have a value of zero. 

As described above, the context field maintains context across multiple 
calls to the service. The context field can have the following values: 

- zero - When the context field is zero, the service attempts to set entries 
in the object_id field beginning with the object id of the first object found 
in the object container. 

- nonzero - When the context field is nonzero, the service attempts to set 
entries in the object_id field beginning with the object id of the next object 
found in the object container. 

For the initial call, the caller sets the value of the context field to 0. For 
subsequent calls when additional object ids can be returned, the caller 
should not modify the value of the context field. 

Logical names are returned in the e$c_logical_name_list item. This item 
is of tjHpe e$logical_name_list. The e$logical_name_list type is made up of 
the following fields: 

- length - This field is set by the caller and indicates to the service the 
number of entries in the logical_name field. 

- last_valid_entry - This field is set by the service and indicates to the 
caller the last entry in the logical_name field that contains a vahd value. 

- context - This field maintains context across multiple calls to the service. 
It is set by the caller and the service. 

- logical_name - This field is set by the service and indicates to the caller 
the logical names in the object container's logical name table. 

The use of the last_valid_entry and the context fields is similar as 
described for the object id list and is not described. 

Note that the caller can request object ids and logical names in the same 
item list. If more information can be returned for either the object id 
list or the logical name list, the status returned is status$_normal. If no 
more information can be returned for either list, the status returned is 
status$_no_moreJurfo. In both cases, the caller should examine the last_ 
valid_entry in each Hst to determine the nimiber of entries, if any, were 
returned. 



ARGUMENTS 



object_container_id 

Supplies the object id of the object container for which information 
is returned. The object id identifies either a container directory or a 
container. 

item_!ist 

SuppHes the item list identifying the information the service should 
return. 
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code 



pointer type 



action 



e$c_objectJdJist 
e$c_logical_nanie_list 



e$object_id_list 
e$logical_name_list 



Returns a list of object ids that identify the 
objects in the object container. 

Returns a list of logical names contained in the 
object container's logical name table. 



RETURN 
VALUES 



status$_rrarmal 



status$_no_moreJnfo 



status$Jnvalid_objectJd 

status$_obJ6ct_type_ 
mismatch 



normal, successful completion. The object container 
was found and some of the object ids or logical 
names were returned. A subsequent call to this 
sen^ice may return additional information. 

normal, successful completion. The object container 
was found and all of the object ids or logical names 
were returned. A subsequent call to this service will 
not return additional information. 

invalid object id. 

the object type of the specified object container was 
not a container directory or container. 
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os$get__objectJnformation 

( 

IN objectjd : e$object_id; 

IN itemjist : POINTER e$ltemjlst_type; 

) RETURNS status; 



DESCRIPTION 



The os$get_object_infonnation service returns information about the 
specified object. The information is control information about the object 
and is general for all objects. 



ARGUMENTS objectjd 

Supplies the object id of the object for which information is returned. 

/fem_//sf 

Supplies the item list identifying the information the service should 
return. 



code 



pointer type 



action 



e$c_pointer_count 


Integer 


e$c_object_id_count 


integer 


fl.$c level 


e$ievel 


e$c_object_1ype_name 


string 


8$c_otd_id 


8$objectJd 


e$c_object_containerJd 


e$object_id 



e$c_principaI_objectJd 



e$objectJd 



e$c_nonpaged_pool_charge integer 

e$c_paged_pool_charge integer 

e$o_name varying_string 



Returns the number of outstanding pointers to 
the object. 

Returns the number of object ids that identify the 
object. 

Returns the level of visibility of the object. The 
level can be e$c_process_level, e$cJobJevel, 
or e$c_systemjevel. 

Returns the object type name of the object. 

Returns the object id of the object's OTD. 

Returns the object id of the object's object 
container. This object id identifies either a 
container directory or a container. This field is 
valid only if the object's principal id has not been 
deleted. See e$c_object_state. 

Returns the object id of the object's principal id. 
This field is valid only if the object's principal id 
has not been deleted. See e$c_object_state. 

Returns the amount of nonpaged pool charged 
when the object was Inserted into its object 
container. 

Returns the amount of paged pool charged when 
the object was inserted into its object container. 

Returns the object's name. This field is valid 
only if the object's principal id has not been 
deleted. See e$c_object_state. 
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code 



pointer type 



action 



e$c_owner 

e$c_acl 

e$c_ailocation_obJ6ctJd 

e$c_mode 

e$c_object_state 



e$identifier 

e$access_control_list 

e$objectJd 

k$processor_mode 

set of e$object_state 



e$c_oid_object_containerJd 8$obJGct_id 



e$c_oidJevei 



8$c_oid_objectJd_type 



e$level 



8$obJ8CtJd_type 



Returns the object's owner. 

Returns the object's access control list. 

Returns the object Id of the object's allocation 
object. This field is valid only if the object is 
allocated. See e$c_object_state. 

Returns the processor mode of the object. The 
mode of the object can be k$c_user or l^c_ 
kennel. 

Returns information about the current state of the 
object. The states are: e$c_transferjnhibit — 
the object cannot be transferred. e$c_reference_ 
inhibit — reference ids cannot be created to 
identify the object. e$c_temporary — the object 
has been marked as temporary. e$c_dispatcher_ 
object — the object has a kernel dispatcher 
object. This allows the object to be waited on. 
e$c_allocated — the object is allocated. e$c_ 
principal_id_deleted — the principal id of the 
object has been deleted. e$c_transferred — the 
object has been transferred. 

Returns the object id of the object container 
through which the object is identified by the 
specified object id. 

Returns the level of visibility of the object when 
identified by the specified object, id. The level 
can be e$c_processJevel, e$cJob_level, or 
e$c_system_level. 

Returns the type of object id. The type of id can 
be e$c_principal_id or e$c_reference_id. 



RETURN 
VALUES 



status$_normal 
status$Jnvalid_objectJd 



normal, successful completion, 
invalid object id. 
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os$get__otdJnformatlon 

( 

IN otdjd : e$object_id; 

IN itemjist : POINTER e$ltemjist_type; 

) RETURNS status; 



OESCRIPTION "^^ os$get_otd_information service returns information about the specified. 

object. 



ARGUMENTS 



otdJd 

Supplies the object id of the otd object for which information is returned. 

itemjist 

Supplies the item list identifying the information the service should 
return. 



code 


pointer type 


action 


e$c_object_type_name 


string 


Returns the name of tlie object type described 
by the OTD. 


e$c_object_count 


Integer 


Returns the count of the number of objects of 
this type. 


e$c_waitabia 


boolean 


Returns a value of true if objects of the type 
described by the OTD can be waited on. 
Returns a value of false If objects cannot be 
waited on. 


e$c_create_disable 


boolean 


Returns the state of the create disable flag. If 
the value is false, objects of this type can be 
created. If the value is true, objects of this type 
cannot be created. 





RETURN 
VALUES 



status$_normal 

status$_invalid_objectJd 

status$_object_type_ 
mismatch 



normal, successful completion. 

invalid object id. 

the object type of the specified object was not an otd. 
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os$mark_tem porary 

( 

IN objectjd : e$object_id; 
) RETURNS status; 



DESCRIPTION Th^ os$mark_temporary service marks the specified object as temporary. 

This service is used to cause the principal id of an object to be deleted 
v«rhen all reference ids to the object have been deleted. If the principal id 
has already been deleted, the last deleted reference id causes the object to 
be deleted. 

Only job and system level objects can be marked as temporary. 

Container directories and containers cannot be marked as temporary. 



ARGUMENTS 



objected 

Supplies the object id of the object to mark as temporary. 



RETURN 
VALUES 



status$_normal 

status$Jnvalid_object_id 

status$Jnvalid_object_level 

status$_already_temporary 

status$_temporary_not_ 
allowed 



normal, successful completion. 

invalid object id. 

the object is a process level object. 

the object is already temporary. 

the object cannot be marked as temporary. 
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os$set__object__name 



( 

IN objectjd : e$object_icf; 
IN name : string (*); 
) RETURNS status; 



DESCRIPTION 



The os$set_object_iiame service sets the specified object's name and inserts 
the name in the object's object container object name table. 

The name of an object can be set only if the principal id of the object 
exists. 



ARGUMENTS object id 

Supplies"Sie object id of the object whose name is set. 

name 

Supples the name that the object name's name is set to. 



RETURN 
VALUES 



status$_normal 

status$_invalid_object_id 

status$_duplicate_object 



normal, successful completion. 

invalid object id. 

abject found having the same mode, type, and name. 
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os$transfer_mark___temporary 

( 

IN containerjd : e$object_id; 
IN delete : boolean - false; 
IN OUT objectjd : e$obJectJd; 
) RETURNS status; 



DESCRIPTION 



The os$transfer_mark_temporary service transfers the object along with 
its name to a more visible conta^er and marks the object as temporary. 

When an object is transferred to the target container, it is possible that £in 
object already exists having the same name, object type, and mode. If a 
duplicate object does exit, the caller can specify the action to perform. If 
the action is not to delete the object specified by the caller, the service does 
not transfer the object and rettims an error status. Note that the object 
id is unchanged. If the action is to delete the object, the service creates 
a reference id to the already existing object, deletes the object id of the 
object specified by the caller, and returns the reference id to the caller. 
The reference id is retinmed via the object_id param.eter. 

If a duplicate object does not exist,^ the service transfers the object to 
the target container, creates a reference id to the object, and returns the 
reference id. to the caller. The reference id is returned via the objectjd 
parameter. 

The object cannot be transferred if any one of the follovdng conditions are 
true: 

- the object has reference ids. This means that the object id specified by 
the object_id parameter is the principal id of the object. - the object is 
not allowed to be transferred. - an object having the ssime name, type, 
and mode already exists in the target container and the delete action was 
specified as false. 

Container directories and containers cannot be transferred and marked as 
temporary. 



ARGUMENTS 



contamer_id 

Supplies the object id of the container into which the object is transferred. 

delete 

Supplies the action to perform if a duplicate object is found in the 
container. If the value is false, the service does not transfer the specified 
object and returns an error status. If the value is true, the service creates 
a reference id to the already existing object, deletes the object specified 
by the caller, and returns the reference id to the caller. If a value is not 
specified, a value of false is assumed. 
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object_id 

Supplies the object id of the object that is transfered and marked 
t«nporary. This object id must be the object's principal id. Returns the 
reference id of the temporary object. 



RETURN 
VALUES 



status$_normal 

status$jnvalid_abjectjd 

status$Jnvalid_container_id 

status$_object_type_ 
mismatch 

status$_object_alr8ady_tem p 

status$_temporary_not_ 
allowed 

status$_duplicate_temporary 

status$_duplicate_not_ 
temporary 

status$jnvalld_targetjevel 

status$_obJ8ct_reference_ids 

status$Jnvalid_object_id_ 
count 



normal, successful completion. 

invalid object id. 

invalid container id. 

tine object type of the specified container was not a 
container. 

the object is already temporary. 

the object cannot be marked as temporary. 

a duplicate object exists in the target container and is 
temporary. 

a duplicate object exists in the target container and is 
not temporary. 

the level of the target container is not more visible 
than the original container. 

the object id has reference ids. 

the object id count of the specified object is not 1 . 
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os$translate_object_name 

( 

IN object_container_id ; e$object_id = DEFAULT; 

IN name : string (*); 

IN obj'ect_type_name : string (*); 

IN casejsensitive : boolean = true; 

OUT objectjd : e$object_id; 

) RETURNS status; 



DESCRIPTION 



The os$translate_object_naine service searches the specified object 
container for an object having the specified object name and object type 
name. If an object is found, the service returns the object id of the object. 
The object id is used as input to other services to identify the object that 
the service is to operate on. 

The service locates the object name using one of two search methods as 
specified by the case_sensitive parameter. If the value is false, the service 
performs a case blind search. If the value is true, the service performs a 
case sensitive search. 

A case blind search locates the first object name whose uppercase 
representation matches the uppercase representation of the object name 
specified by the caller. Multiple object names in the object container may 
match but only the first object name found is matched. 

A case sensitive search locates the object name whose name exactly 
matches the object name specified by the caller. Only one object name can 
match. 

The service matches the object type name using a case sensitive search. 

The caller can optionally specify the object contedner parameter. If the 
parameter is not specified, tbe service searches the object name tables of 
the process, job, and system container directories. If a match is found, 
the object id that identifies the object is returned to the caller. If tjte 
parameter is specified, the service searches the object name table of the 
specified object container. ; 

If the previous mode of the caller is user, the service tries to match a user 
mode object having the specified name and object type name in the target 
object container. If a name is found, the object id of the user mode object 
is retxnmed to the caller. If a name is not found, the service tries to match 
a kernel mode object with the same search criteria. If a name is found, the 
object id of the kernel mode object is returned to the caller. 



ARGUMENTS 



object_contamer_id 

Supplies the name of the object container whose object name table 
is searched. The object id identifies either a container directory or a 

container. 
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name 

Supplies the name of the object to find. 

object_type_name 

Supplies the object type name of the object to find. 

case_se/7S/*/Ve 

Supplies the search method used to locate the object name. A value 
of false indicates a case blind search. A value of true indicates a case 
sensitive search. 

object_id 

Returns the object id of the matching object. 



RETURN 
VALUES 



status$_normal 
status$Jnvalid_name_length 

status$_invalid_object_type 

status$_invalid_object_id 

status$_object_type_ 
mismatch 

status$_object_name_hot_ 
found 



normal, successful completion. 

length of the object name or object type name was 
not valid. 

invalid object type specified by the object type name. 

the object id of the object container is invalid. 

the object specified by the object container id was 
not a container directory or a container. 

object name not found. 
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os$createJogical__name 

( 

!N obJect_container_id : e$object_id; 

IN logical_name : string (*); 

IN supersede : boolean = true; 

IN loglcal_name_attributes : SET e$lognam_attributes [..] =[]; 

IN OUT equlvalence_name_list : e$equivalence_name_list; 

) RETURNS status; 

DESCRIPTION Th© os$create_logical_naine service creates the specified logical name in 

the specified object container. 

Before the service creates the logical name, it performs a case sensitive 
search for the logical name in the object container. If a logical name is not 
found, the service creates the logical name. If a logical name is found, the 
service takes the action specified by the supersede parameter. If a value of 
false is specified, the logical name specified by the caller is not created and 
the service fails. If a value of true is specified, the logical name that was 
found is deleted and the logical name specified by the caller is created. 

Logical names and eqmvalence names contain 1-256 characters. The 
characters that form the name can be any character in the character set. 

A logical name can have 1-128 equivalence names. 

Equivalence names are specified in the equivalence_name_list parameter. 
This parameter is of type e$equivalence_name_hst. The e$equivalence_ 
name_list type is made up of the following fields: 

- length - This field is set by the caller and indicates to the service the 
number of entries in the equivalence_name field. 

- last_valid_entry - This field is set by the caller and indicates to the 
service how many valid entries are in the equivalence_name field. 

- context - This field is set by the service when an entry in the equivalence_ 
name field is invalid. The context field indicates to the caller the entry 
that is invaHd. 

- eqmvalence_name - This field is set by the caller and indicates to the 
service the equivalence name or names to assocaiate with the specified 
logical name. 

A logical name can have attributes associated with it. An attribute denotes 
a characteristic of the logical name. The following logical name attributes 
are defined: 

- confine - The confine attribute indicates that the logical name should not 
be transferred when an object container is transferred. If the logical name 
has the confine attribute, the object container transfer service deletes the 
logical name as the transfer is performed. The caller gives the logical 
name the confine attribute by setting e$c_confine_lognam_attr in the 
logical_name_attributes parameter. If the confine attribute is not given to 
the logical name, the logical name is transferred. 
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- noalias - The noalias attribute indicates to os$create_logical_naine that 
the logical name cannot be duplicated in the object container at an outer 
access mode. If another logical name with the same name already exists 
in the object container at an outer access mode and the caller of os$create_ 
logical_name specifies the noalias attribute, os$create_logical_name first 
deletes the logical name at the outer access mode and then creates the 
logical name at the inner access mode. The caller gives the logical name 
the noalias attribute by setting e$c_noalias_lognam_attr in the logical_ 
name_attributes parameter. If the noalias attribute is not given to the 
logical name, the logical name can have a logical name with the same 
name at an outer access mode. 

- noshow - The noshow attribute indicates to the caller of os$translate_ 
logical_name tibat the logical name should not be displayed. General 
show logical name utilities examine this attribute to determine if the 
logical name should be displayed. The caller gives the logical name the 
noshow attribute by setting e$c_noshow_lognam_attr in the logical_name_ 
attributes parameter. If the noshow attribute is not given to the logical 
name, the logical name can be displayed. 

Each entry in the equivalence name list specifies an equivalence name 
and the attributes to give to the eqtiivalence name. An attribute denotes 
a characteristic of the equivalence name. The following equivalence name 
attributes are defined: 

- concealed - The concealed attribute indicates to the caller of os$translate_ 
logical_name that the equivalence name should not be displayed. General 
show logical name utilities examine this attribute to determine if the 
equivalence name should be displayed. The caller gives the equivalence 
name the concealed attribute by setting the e$c_concealed_eqvnam_attr 
in the attributes field of the equivalence name entry. If the concealed 
attribute is not given to the equivalence name, the equivalence name can 
be displayed. 

- terminal - The terminal attribute indicates to the caller of os$translate_ 
logical_name that the equivalence name should not be translated as if it 
were a logical naime. The caller gives the equivalence name the terminal 
attribute by setting the e$c_terminal_eqAmam_attr in the attributes field 
of the equivalence name entry. If the terminal attribute is not given to the 
equivalence name, the equivalence name can be translated as if it were a 
logical name. 



ARGUMENTS 



object_contamer_id 

Supplies the object id of the object container whose logical name table 
the logical name is created in. The object id identifies either a container 
directory or a container. 

logical_name 

Supplies the name of the logical name to create. The size of the name can 
be 1 to 255 characters. Any character can be used in the logical name. 

supersede 

SuppUes the action to perform if a matching logical name is found in the 
object container's logical name table. 

log!cal_name_attnbutes 

Supplies a set containing the attributes of the logical name. 
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equivalence_name_nst 

Supplies the eqtrivalence names associated with the logical name. Returns 
in the context field the number of the entry that is invalid. If all entries 
are valid, the value of the context field is 0. 



RETURN 
VALUES 



status$_normal 

status$Jogical_name_ 
superseded 

status$Jnvalid_object_id 

status$_object_type_ 
mismatch 

status$_invalid_name_length 

status$_invalid_eqv_name_ 
count 

status$_duplicateJogical_ 
name 

status$_quota_exceeded 



normal, successful completion. The logical name was 
created. 

normal, successful completion. The logical name was 
created and a previously existing logical name with 
the same name was deleted. 

invalid object container id. 

the object type of the specified object container was 
not a container directory or container. 

length of the logical name or the equivalence name 
was not valid. 

the count of the number of equivalence names was 
invalid. 

duplicate logical name was found. 

quota was exceeded while trying to create the logical 
name. 
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os$deleteJogical_name 



( 

IN obj'ect_container_id : e$object_id; 
IN logical_name : string (*); 
) RETURNS status; 



DESCRIPTION 



The os$delete_logical_naine service deletes the specified logical name from 
the specified object container. 

The service performs a case sensitive search for the logical name in the 
object container. 



ARGUMENTS 



obJect_container_fd 

Supplies the object id of the object container whose logical name table 
is searched. The object id identifies either a container directory or a 
container. 

logical_name 

Supplies the logical name to delete. 



RETURN 
VALUES 



status$_normal 

status$Jnvalid_objectJd 

status$_object_type_ 
mismatch 

status$_invalid_name_length 

status$Jogical_name_not_ 
found 



nomial, successful completion. 

invalid object container id. 

the object type of the specified object container was 
not a container directory or container. 

length of the logical name was not valid. 

logical name was not found. 
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os$translateJogical_name 

{ 

IN object_container_id : e$object_id; 

IN logical_name : string (*); 

IN casejsensitive : boolean = true; 

IN OUT equivalence_namejist : e$equivalence_name_llst; 

OUT loglcal_name_attrlbutes : SET e$lognam_attnbutes [..] OPTIONAL; 

) RETURNS status; 

DESCRIPTION The os$translate_logical_naine service searches the specified object 

container for the specified logical name. If the logical name is foxmd, 
the service rettims the logical name's equivalence names. 

The service locates the logical name in the object container using one of 
tvro search methods as specified by the case_sensitive parameter. If the 
value is false, the service performs a case blind search. If the value is 
true, the service performs a case sensitive seardi. 

A case blind search locates the first logical name v^hose uppercase 
representation matches the uppercase representation of the logical name 
specified by the caller. Multiple logical names in the object container may 
match but only the first logical name found is matched. 

A case sensitive search locates the logical name whose name exactly 
matches the logical name specified by the caller. Only one logical name in 
the object container can match. 

Equivalence names sure returned in the equivalence_nam[e_Ust parameter. 
This parameter is of type e$eqmvalence_name_list. The e$equivalence_ 
name_list type is made up of the following fields: 

- length - This field is set by the caller and indicates to the service the 
nixmber of entries in the equivalence_name field. 

- last_valid_entry - This field is set by the service and indicates to the 
caller the last entry in the eqmvalence_name field that contains a vahd 
value. 

- context - This field maintains context acrxjss multiple calls to the service. 
It is set by the caller and the service. 

- equivalence_name - This field is set by the service and indicates to the 
caller the equivalence name or names assocsdated vdth the logical name. 

As described above, the last_valid_entry field indicates the last entry in 
the equivalence_name field that contains a valid value. This field can have 
the foUovring values: 

- If the value of this field is zero, the service did not return any equivalence 
names associated with the logical name. A subsequent call to the service 
would not return additional equivalence names. 
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- If the value is non-zero and is less than the maximum number of entries, 
the service returned all the equivalence names associated with the logical 
name. A subsequent call to the service would not retrnm additional 
equivalence names. 

- If the value is non-zero and is equal to the maximum number of entries, 
the service may have returned all the equivalence names associated with 
the logical name. The caller must examine the status returned by the 
service to determine if all the equivalence names were returned. If the 
status returned was status$_no_more_info, the service returned all the 
equivalence names and a subsequent call to the service would not return 
additional equivalence names. If the statiis returned was status$_normal, 
the service did not return all the equivalence names and a subsequent csdl 
to the service would return additional equivalence names. 

As described above, the context field maintains context across multiple 
calls to the service. The context field can have the following values: 

- zero - When the context field is zero, the service attempts to set entries 
in the equivalence_name field beginning with the first equivalence name 
associated with the logical name. 

- nonzero - When the context field is nonzero, the service attempts to set 
entries in the eqmvalence_name field beginning with the next equivalence 
name associated with the logical name indicated by the value in the 
context field. 

For the initial call, the caller sets the value of the context field to 0. For 
subsequent calls when additional equivalence names can be returned, the 
caller should not modify the value of the context field. 

Note, if multiple calls to the service are required to return all the 
equivalence names, the logical name may be deleted in between the 
calls. 



ARGUMENTS 



object_container_id 

Supplies the object id of the object container whose logical name table 
is searched. The object id identifies either a container directory or a 
container. 

logicaljname 

Supplies the name of the logical name to translate. 

casejsensltive 

Supplies the search method used to locate the logical name. A value 
of false indicates a case blind search. A value of true indicates a case 
sensitive search. 

equivalence_name_nst 

Supphes (in the length field) the number of entries in the equivalence 
name field. Supplies (in the context field) the context of the service. 
Returns (in the last_vaHd_entiy field) the last entry in the equivalence, 
name field that contains a vaHd value. Returns (in the context field) the 
context for the next call to the service. Returns (in the equivalence_name 
field) some or aU of the eqtiivalence names associated with the logical 
name. 



2-7 



DIGITAL - Confidential and Proprietary - Restricted Distribution 
os$translateJogical_name 



logicaljriamejattributes 

Returns a set containing the attributes of the logical name. See os$create_ 
logical_name for an explanation of the logical name attributes. 



RETURN 
VALUES 



status$_normal 



status$_no_moreJnfo 



status$Jnvalid_object_id 

status$_object_type_ 
mismatch 

status$Jnvalicl_name_langth 

status$Jogical_name_not_ 
found 



nomial, successful completion. The logical name 
was found and some of the equivalence names were 
returned. A subsequent call to this service may 
return additional information. 

normal, successful completion. The logical name 
was found and all of the equivalence names were 
returned. A subsequent call to this service will not 
return additional Information. 

invalid object container id. 

the object type of the specified object container was 
not a container directory or container. 

length of the logical name was not valid. 

logical name was not found. 
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os$wait_multiple 

( 

IN OUT objectjdjist : e$objectJd_list; 
IN time_out : largejnteger OPTIONAL; 
IN waitjtype : e$wait_type = e$c_wait_any; 
OUT object_number : integer; 
) RETURNS return_status : status; 



DESCRIPTION 



The os$wait_multiple service suspends the execution of the caller until 
one or all of the specified objects become signalled or the specified time 
interval expires. 

The object ids that identify the objects to wait on are specified in the 
object_id_list parameter. This parameter is of tjrpe e$object_id_Hst. The 
e$object_id_list tjrpe is made up of the following fields: 

- length - This field is set by the caller and indicates to the service the 
number of entries in the object_id field. 

- Ia3t_valid_entry - This field is set by the caller and indicates to the 
service how many valid entries are in the object_id field. 

- context - This field is set by the service when an entry in the object_id 
field is invalid. The context field indicates to the caller the entry that is 
invalid. 

- object_id - This field is set by the caller and indicates to the service the 
object ids that identify the objects to wait on. 



ARGUMENTS 



objectjdjist 

Supplies the object ids that identify the objects to wait on. Returns in 
the context field the number of the entry that is invalid. If all entries are 
valid, the context is 0. 

time_out 

The amount of time in 100 nanosecond units that can expire before the 
wait is timed out. 

waitjtype 

Supplies the type of wait. If e$c_wait_any is specified, any object in the 
object list that is signalled satisfies the wait. If e$c_wait_all is specified, 
all objects in the object list must be signalled to satisfy the wait. If a value 
is not specified, e$c_wait_any is assumed. 

object_number 

Returns the number of the object in the object id Hst that satisfied the 
wait. If the wait times' out, the object number is 0. 
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RETURN 
VALUES 



status$_normal 

status$Jnvaiid_objectJd 

status$_invalid_object_count 

status$_wait_not_supported 
status$ wait timeout 



normal, successful completion, 
invalid object id. 

the count of the number of objects to wait on was 

invalid. 

wait not supported by the specified object. 

wait was not satisfied before the time out period. 
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os$wait_single 



( 

IN objectjd : e$obJect_ld; 

IN timejout : largejnteger OPTIONAL; 

) RETURNS returnjstatus : status; 



DESCRIPTION 



The os$wait_single service suspends the execution of the caller until the 
specified object becomes signalled or the specified time interval expires. 



ARGUMENTS objectjd 

SuppUes the object id that identifies the object to wait on. 

time_out 

The amount of time in 100 nanosecond units that can expire before the 
wait is timed out. 



RETURN 
VALUES 



status$_normai 
status$_invaiid_object_id 

status$_object_type_ 
mismatch 

status$_wait_not_supported 

status$ wait timeout 



normal, successful completion. 

invalid object id. 

object type specified does not match the object type 
of the object. 

wait not supported by the specified object. 

wait was not satisfied before the time out period. 
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os$clear event 



( 

IN eventjd : e$object_id; 
OUT previous_state : boolean; 
) RETURNS retum_status : status; 



DESCRIPTION 



The os$clear_event service clears the state of the specified event to not 
signalled. 



ARGUMENTS 



event_id 

Supplies the object id of the event to clear. 

previous_state 

Returns the previous state of the event. A value of false indicates that the 
state of the event was clear (not signalled). A value of true indicates that 
the state of the event was set (signalled). 



RETURN 
VALUES 



status$_normal 

status$Jnvalid_objectJd 

status$_object_type_ 
mismatch 



normal, successful completion. 

invalid object id. 

object type specified does not matcii the object type 
of the object. 
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os$create_event 

( 

OUT eventjd : e$object_ld; 

IN objectjDarameters : e$object_parameters = DEFAULT; 

IN autoclear_flag : boolean = false; 

IN initial_state : boolean = false; 

) RETURNS retum_status : status; 



DESCRIPTION Th® os$create_event service creates an event object. 

An event can have two states: dear and set. When an event is clear it 
is not signalled. When an event is set it is signalled. Only an event that 
has been signalled satisfies a wait. An event is signalled by calling os$set_ 
event. 

The creator of an event can specify that the event is automatically cleared 
when the event satisfies a wait. If multiple threads are waiting on the 
event, only the first thread's wait is satisfied; the remaining threads must 
wait until the event is set again. If the object is created without automatic 
clearing, the event remains set until expHdtly deared. If multiple threads 
are waiting on the event, all the waits are satisfied. An event is cleared by 
calling os$clear_event. 



ARGUMENTS 



eventjid 

Returns the object id of the created event. 

object_parameters 

Supplies the object container in which the object is inserted, the name of 
the object, and the access control Kst (ACL) of the object. If this argument 
is not suppUed or if it is suppUed but not all vsilues in the object parameter 
record are supplied, the service appHes default values. The default object 
container is the process private container, the default name is none, and 
the default ACL is none. 

autodear_flag 

SuppHes the action taken when a wait on the event is satisfied. If the 
value is false, the state of the event is not changed; otherwise, the state is 
cleared. If this argument is not supphed, the state is not changed. 

initialjstate 

SuppUes the initial state of the event. If the value is false, the initial state 
is cleared (not signalled); otherwise, it is set (signalled). If this argument 
is not supplied, the state is cleared. 
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RETURN 
VALUES 



status$_normal 

status$_invalid_objectJd 

status$_object_type_ 
mismatch 

status$Jnvalid_object 

status$_duplicate_object 



normal, successful completion. 

invalid object id. 

object type specified does not match the object type 
of the object. 

invalid object. 

duplicate object found in object container. 



status$_object_container_fu" object container full. 
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os$pulse_event 



( 

IN eventjd : e$object_id; 
OUT previousjstate : boolean; 
) RETURNS return_status : status; 



DESCRIPTION 



"Hie os$pulse_event service sets the state of the specified event to 
signalled, services aU the threads waiting on the event, and clears the 
state of the specified event to not signalled. 

The service ignores the autoclear flag that w^as specified when the event 
was created 



ARGUi\/IENTS 



event_id 

Supplies the object id of the event to clear. 

previous_state 

Returns the previous state of the event. A value of false indicates that the 
state of the event was clear (not signalled). A value of true indicates that 
the state of the event was set (signalled). 



RETURN 
VALUES 



status$_narmal 

status$_invalid_objactJd 

status$_obiect_type_ 
mismatch 



normal, successful completion. 

invalid object id. 

object type specified does not match the object type 
of the object. 
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os$read_event 

( 

IN eventjd : e$object_id; 

OUT state : boolean; 

) RETURNS return_status : status; 

DESCRIPTION Th® os$read_eveiit service reads the state of the specified event. 



ARGUI\AENTS 



event_id 

Supplies the object id of the event to read. 

State 

Returns the current state of the event. A value of false indicates that the 
state of the event is clear (not signalled). A value of true indicates that 
the state of the event is set (signalled). 



RETURN 
VALUES 



status$_normal 

status$_invalid_objectJd 

status$_object_type_ 
mismatch 



normal, successful completion. 

invalid object id. 

object type specified does not match the object type 
of the object. 
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os$set__event 

( 

IN eventjd : e$objectJd; 
OUT previous_state : boolean; 
) RETURNS returnjstatus : status; 



DESCRIPTION "^^ os$set_event service sets the state of the specified event to signalled. 



ARGUMENTS 



event_!d 

Supplies the object id of the event to set. 

previous_state 

Returns the previous state of the event. A value of false indicates that the 
state of the event was clear (not signalled). A value of true indicates that 
the state of the event was set (signalled). 



RETURN 
VALUES 



status$_normal 

status$_invaHd_objectJcl 

status$_object_type_ 
mismatch 



normal, successful completion. 

invalid object id. 

object type specified does not matcli the object type 
of the object. 
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os$create_semaphore 

( 

OUT semaphorejd : e$object_id; 

IN object_parameters : e$object_parameters; 

IN initial_count : integer; 

IN maximum_count : integer; 

) RETURNS status; 



DESCRIPTION This os$create_semaphore service creates a semaphore object. 

(The following description is brought to you by the Kernel.) A semaphore 
object is used to control access to a resource but not necessarily in a 
mutually exclusive fashion. A semaphore acts as a gate through which a 
variable number of threads can pass concurrently, up to a specified limit. 
The gate is open (signaled state) as long as there are resources available. 
When the number of resources that may be concurrently in use has been 
exhausted, the gate is closed (not-signaled state). The gating mechanism 
of a semaphore is implemented by a counter. Waiting on a semaphore 
waits until a resource is available and decrements the count. Releasing 
the semaphore increments the count and allows another thread to pass " 
through the gate. 



ARGUMENTS 



semaphore_id 

Returns the object id of the created semaphore. 

object_parameters 

Supplies the object container in which the object is inserted, the name of 
the object, and the access control list (ACL) of the object. If this argument 
is not supplied or if it is supplied but not all values in the object parameter 
record eire supplied, the service applies default values. The default object 
container is the process private container, the default name is none, and 
the default ACL is none. 

initial_count 

Supplies the initial count of the semaphore. The intitial count must be 
less than or equal to the maximum count. 

maximum_count 

SuppUes the maximiun count the semaphore can attain. The maximumL 
count must be greater than zero. 
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RETURN 
VALUES 



status$_normal 

status$Jnvaiid_obiectJd 

status$_object_type_ 
mismatch 

status$_dupiicate_object 

status$_object_container_fuil 

status$_invalidJnitial_count 

status$_invalid_maximum_ 
count 



normal, successful completion. 

invalid object id. 

object type specified does not match the object type 
of the object. 

duplicate object found in object container. 

object container full. 

the value specified as the initial count was greater 
than the maximum. 

the value specified as the maximum count was not 
greater than zero. 
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os$read_semaphore 

( 

IN semaphorejd : e$object_id; 
OUT count : integer; 
) RETURNS status; 



DESCRIPTION "^^ os$rea(L.semapliore service reads the count of the specified semaphore. 



ARGUMENTS semaphorejd 

Supplies the object id of the semaphore object to read. 

count 

Returns the count of the semaphore. 



RETURN 
VALUES 



status$_normal 

status$_invalid_objectJd 

status$_object_type_ 
mismatch 



normal, successful completion. 

invalid object id. 

object type specified does not match the object type 
of the object. 
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os$release_semaphore 

( 

IN semaphorejd : e$object_id; 
IN release_count : Integer = 1; 
OUT previousjcount : integer; 
) RETURNS status; 



DESCRIPTION 



The os$release_semaphore service releases the specified semaphore. This 
action causes the semaphore count to be incremented by the specified 
count. If the count was before it was incremented, the the state of the 
semaphore is set to signaled. 

The release_count argument specifies the value that is added to the 
semaphore cotmt. If a value for this argument is not specified, the 
semaphore count is incremented by 1. The resulting sem^aphore count 
must not exceed the maximum count of the semaphore. 



ARGUMENTS 



semaphore_id 

Supplies the object id of the semaphore object to release. 

retease_count 

Supphes the value that is added to the semaphore count. 

previous_count 

Returns the count of the semaphore before the coiont was incremented. 



RETURN 
VALUES 



status$_normal 

status$_invalid_objectJd 

status$_object_type_ 
mismatch 

status$_invalid_release 



normal, successful completion. 

invalid object id. 

object type specified does not matcii the object type 
of the object. 

the release of the semaphore caused the the count 
to exceed the maximum count. 
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os$cancel timer 



( 

IN timer_id : e$object_id; 
OUT timerjstate : boolean; 
) RETURNS status; 



DESCRIPTION 



Cancels a timer object. If a timer object has been set with an AST, only 
the thread that originally set the timer may cancel it. 



ARGUMENTS 



timerjd 

supphes the object id of the timer object 

timerjstate 

returns true if the timer was currently active, false otherwise 



RETURN 
VALUES 



status$_normai 

status$_access_violation 

status$Jnvalid_cancel_timer 

others 



the service completed without errors 

a specified parameter is not accessable 

the calling thread is not the thread that set the timer 
with an AST 

object id translation errors 
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os$create__timer 

( 

OUT timerjd : e$objectJd; 

IN object_parameters : e$object_jDarameters = DEFAULT; 

) RETURNS status; 



DESCRIPTION 



Creates and initializes a timer object. The default object container is 
process private 



ARGUMENTS 



timerjd 

returns the object id of the resulting timer object 

object_parameters 

suppUes the object type independent parameters governing the creation of 
the timer object 



RETURN 
VALUES 



status$_normal 

status$_access_violation 

status$_duplicate_abject 

others 



the service completed without errors 

a specified parameter is not accessable 

a timer with the same name already exists in the 
specified container 

object id translation errors 
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os$read_timer 



( 

IN timerjd : e$object_id; 
OUT timer_state : boolean; 
) RETURNS status; 



DESCRIPTION reads the signaled state of a timer object 



ARGUMENTS 



timerjd 

supplies the object id of the timer object 

timerjstate 

returns true if the timer is in the signaled state , false otherwise 



RETURN 
VALUES 



status$_normal 

status$_access_vioiation 

others 



the service completed without errors 
a specified parameter is not accessable 
object id translation errors 
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os$set__tfmer 

( 

IN timerjd : e$objectJd; 

IN due_tlme : largejnteger; 

IN astjDrocedure : k$normal_ast_routine = NIL; 

IN ast_parameter : POINTER anytype CONFORM = NIL; 

) RETURNS status; 



DESCRIPTION 



Sets a timer to expire in due_time. Timers are waitable objects. Waits are 
satisfied when the timer expires. 

When timers are used with ASTs, the system_value parameter is the 
ciirrent system time in absolute UTC. 



ARGUMENTS 



timerjd 

supplies the object id of the timer to set 

duejtime 

supplies the number of 100ns units of time that should elapse before 
the timer expires if due_time is negative, the timer is "relative", or the 
timer will expire (-due_time) units of time after the set timer call is made. 
Positive values of due_time implys absolute time in UTC. 

ast__procedure 

supplies the procedure that should be called when the timer expires. If 
defaulted, no procedure is called. If the previous mode is k$c_user, then 
the procedure is called as a user mode ast procedure, otherwise, it is called 
as a kernel mode ast procedure. 

ast_parameter 

suppUes the context passed to the ast procedure. If the ast procedure is 
defaulted, then this parameter is ignored. ; 



RETURN 
VALUES 



status$_normal 

status$_access_violation 

status$_invalid_cancel_timer 

others 



the service completed without errors 

a specified parameter is not accessable 

the timer is set with an AST, and the calling thread 
is not the thread that originally set the timer with an 
AST 

object id translatiorp errors 
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os$create_exi t_hand ler_process 

{ 

IN handler_procedure : k$normal_ast_routine; 

IN handler_context : POINTER anytype CONFORM = NIL; 

IN handlerjDiacement : e$exit_hand!er_placement = e$c_beglnning_of_ 

list; 

OUT handlerjd : e$exit_handler_id; 

) RETURNS status; 



DESCRIPTION 



This service is used to create a process level exit handler. Exit handlers 
are called as user mode AST routines during exit. Process level exit 
handlers are processed when a the last thread in a process calls os$exit_ 
thread( ), and after all of the thread level exit handlers have been 
processed. The exit handler Hst head stored in the exiting threads PCR 
is processed in order. Each handler found in the Hst is removed and 
then called as an AST routine. This interface supports placement of an 
exit handler at either the beginning or end of the exit handler list head. 
Placement is under the control of the handler_placement parameter v?hich 
defaults to beginning of the list. Once created, a handler is assigned 
a handler_id. This return value may be used to delete an existing exit 
handler. 



ARGUIUIENTS 



handler_procedure 

Supplies the exit handler procedure to be executed when this handler is 
processed 

handlerjcontext 

Supplies a parameter to be passed to the handler_procedure when the 
handler is processed. 

handler_placement 

Supplies exit handler placement control. 

handlerjd 

Returns the handler ID of the exit handler. This argument is only valid if 
the service returns with status$_normal. 



RETURN 
VALUES 



status$_normal 

status$_access_violation 

status$_not_supported 



the service completed without errors 

a specified parameter is not accessible 

an attempt to call this service from a system thread 
was made, or the service was called after kernel 
mode exit processing has started. 
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os$create_exit_handler_thread 

( 

IN hancHer_procedure : k$normal_ast_routine; 

IN handlerjcontext : POINTER anytype CONFORM = NIL; 

IN handlerjDiacement : e$exit_handler_place merit = e$c_beginning_of_ 

list; 

OUT handlerjd : e$exit_hand!er_id; 

) RETURNS status; 



DESCRIPTION 



This service is used to create a thread level exit handler. Exit handlers 
are called as user mode AST routines during exit. Thread level exit 
handlers are processed when a thread calls os$exit_thread( ). The exit 
handler list head stored in the exiting threads TCR is processed in order. 
Each handler found in the list is removed and then called as an AST 
routine. This interface supports placement of an exit handler at either 
the beginning or end of the exit handler list head. Placement is under the 
control of the handler_placement parameter which defaults to beginning 
of the list. Once created, a handler is assigned a handlerjd. This return 
value may be used to delete an existing exit handler. 



ARGUMENTS 



handler_procedure 

SuppUes the exit handler procedure to be executed when this handler is 
processed 

handler_context 

SuppKes a parameter to be passed to the handler_procedure when the 
handler is processed. 

handler_placement 

SuppUes exit handler placement control. 

handlerjid 

Returns the handler ID of the created exit handler. This argument is only 
vaHd if the service returns with status$_normal. 



RETURN 
VALUES 



status$_normal 

status$_access_violation 

status$_not_supported 



the service completed without errors 

a specified parameter is not accessible 

an attempt to call this service from a system thread 
was made, or the service was called after kernel 
mode exit processing has started. 
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os$create_exit_status 



( 



OUT exit_statusjd : e$objectJd; 

IN object_parameters : e$object_parameters = DEFAULT; 

) RETURNS status; 



DESCRIPTION 



Create and initialize an exit status object. If the container id stored in 
object parameters is defaulted, then process private is assumed. 



ARGUMENTS 



ex!t_status_id 

object id of created exit status object 

object_parameters 

the object type independant parameters of the exit status object 



RETURN 
VALUES 



status$_normal 

status$_access_violation 

status$_duplicate_object 

others 



the service completed without errors 

a specified parameter is not accessable 

an exit status object with the same name already 
exists in the specified container 

object id translation errors 
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os$createJob 

( 

OUTjobJd : e$objectJd; 

IN object_parameters : e$object_parameters = DEFAULT; 

IN job_record : e$job_record = DEFAULT; 

IN job_lnltial_contalner : e$object_id = DEFAULT; 

INjob_allocatlonJist : POINTER e$objectJdJlst = NIL; 

IN process_object_parameters : e$object_parameters = DEFAULT; 

IN proce$s_record : e$process_record; 

IN process_public_container : e$objectJd= DEFAULT; 

IN process_private_container : e$object_id = DEFAULT; 

IN process_allocatlon_list : POINTER e$objectJdJlst = NIL; 

IN process_data_block : POINTER quadword_data(*) CONFORM = NIL; 

IN thread_object_parameters : e$object_parameters = DEFAULT; 

IN thread_record : e$thread_record = DEFAULT; 

IN thread_allocationJlst : POINTER e$objectJd_list = NIL; 

IN thread_data_block : POINTER quadword_data(*) = NIL; 

IN threadJmmediatejDarameterl ; POINTER anytype CONFORM = NIL; 

IN thread J mmediate_parameter2 : POINTER anytype CONFORM = NIL; 

IN thread_status : e$obJectJd = DEFAULT; 

) RETURNS status; 

DESCRIPTION Create a job, process, and thread object as specified by the parameters. 

ARGUMENTS jobjd 

Returns the object ID of the resulting job object 

obJect_parameters 

Supplies the object type independent parameters for the job object the 
ACL and container ID are ignored 

job_record 

Supplies the attributes of the job being created. If not present, then values 
are obtained from current user object 

lob_mitial_contalner 

Supplies the job level object container to be transfered into the job level 
container directory for this job. If not present then container directory 
comes up empty 
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job_aUocation_Ust 

Supplies the objects to be allocated to the job object. If not present then no 
objects are allocated to the job 

process_object_parameters 

Supplies the object type independent parameters for the process object the 
ACL and container ID are ignored 

processjrecord 

Supplies the attributes of the process being created 

process_pubUc_container 

Supplies the process level public container to be transfered into the process 
level container directory for the process. If not present then the container 
comes up empty. 

process_private_container 

Supphes the process level private container to be transfered into the 
process level container directory for the process. If not present then 
container comes up empty. 

process_allocation_list 

Supplies the objects to be allocated to the process object. If not present 
then no objects are allocated to the process 

process_data_bIock 

Supplies an arbitrary data block passed to the process 

thread_obj'ect_parameters 

Supplies the object type independent parameters for the thread object the 
ACL and Container ID are ignored 

thread_record 

Supplies the attributes of the thread being created 

thread_anocation_list 

Supplies the objects to be allocated to the thread object. If not present 
then no objects are allocated to the thread 

thread_data_block 

Supplies an arbitrairy data block passed to initial thread. Pointer in TCR, 
if pointer is NIL, then no data block was passed 

thread_immediate_parameter1 

Supplies an immediate parameter passed to thread through TCR 

thread_immediate__parameter2 

SuppHes an immediate parameter passed to thread through TCR 

threadjstatus 

Supplies an exit status object to be bound to the initial thread. If not 
present then the thread is created without an exit status object 
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RETURN 
VALUES 



status$_normal 

status$_access_violation 

status$job_name_exists 

status$_badJob_record 

status$_badJob_init_ 
container 

status$_bad_job_allocation 

status$__process_name_ 
exists 

status$_bad_process_record 

status$_bad_prc_pub_ 
container 

status$_bad_pro_priv_ 
container 

status$_bad_process_ 
allocation 

status$_tliread_name_exists 

status$_bad_thread_record 

status$_bad_thread_ 
allocation 

status$_bad_process_exit_ 
status 

status$_bad_thread_6xit_ 
status 

status$_quota_exceeded 



the service completed without errors 

a specified parameter is not accessabie 

a job object already exists with the name specified in 
the job object parameters 

an invalid job record was specified 

the specfied job initial container can not be transfered 
to the new job 

an invalid job allocation list was specified 

a process object already exists with the name 
specified in the process object parameters 

an Invalid process record was specified 

the specified process public container can not be 
transfered to the new process 

the specified process private container can not be 
transfered to the new process 

an invalid process allocation list was specified 

a thread object already exists with the name specified 
in the thread object parameters 

an invalid thread record was specified 

an invalid thread allocation list was specified 

an error occured translating the object id of the 
specified process exit status object 

an error occured translating the object id of the 
specified thread exit status object 

not enough quota exists to complete the service 
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os$create_process 

( 

OUT processjd : e$object_icf; 

IN object_parameters : e$object__parameters = DEFAULT; 

IN processjrecord : e$process_record; 

IN process_public_container : e$object_id = DEFAULT; 

IN process_prlvate_container : e$object_ld = DEFAULT; 

IN process_allocationJist ; POINTER e$objectJdJist = NIL; 

IN process_data_block : POINTER quadword_data(*) CONFORM = NIL; 

IN thread_object__parameters : e$object_parameters = DEFAULT; 

IN threadjrecord : e$thread_record = DEFAULT; 

IN thread_allocationJist : POINTER e$obJectJdJist = NIL; 

IN thread_data_block : POINTER quadword_data(*) CONFORM = NIL; 

IN thread J mmedlatejDarameterl : POINTER anytype CONFORM = NIL; 

IN threadjmmedlate_parameter2 : POINTER anytype CONFORM = NIL; 

IN thread_status : e$obJectJd = DEFAULT; 

) RETURNS STATUS; 



DESCRIPTION 



Create a Process and thread object as specified by the parameters. Always 
results in the creation of a sub-process 



ARGUMENTS 



processjd 

Returns the object ID of the resulting process object 

obJect_parameters 

Supplies the object type independent parameters for the process object the 
ACL and container ID are ignored \ 

process_record 

Supplies the attributes of the process being created 

process_public_contalner 

Supplies the process level public container to be transfered into the process 
level container directory for the process. If not present then the container 
comes up empty. 

processjprlvatejcontainer 

SuppUes the process level private container to be transfered into the 
process level container directory for the process. If not present then 
container comes up empty. 

process_aUocation_list 

Supplies the objects to be allocated to the process object. If not present 
then no objects are allocated to the process 
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process_data_block 

Supplies an arbitrazy data block passed to the process 

thread_object_parameters 

Supplies the object type independent parameters for the thread object the 
ACL and Container ID are ignored 

thread_record 

Supplies the attributes of the thread being created 

thread_aUocation_list 

Supplies the objects to be allocated to the thread object. If not present 
then no objects are allocated to the thread 

thread_data_block 

Supplies an arbitrary data block passed to initial thread. Pointer in TCR, 
if pointer is NIL, then no data block was passed 

thread_immediate_parameter1 

Supplies an immediate parameter passed to thread through TCR 

thread_immediate_parameter2 

SuppHes an immediate parameter passed to thread through TCR 

thread_status 

Supplies an exit status object to be bound to the initial thread. If not 
present then the thread is created without an exit status object 



RETURN 
VALUES 
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status$_normal 

status$_access_vioiation 

status$_process_name_ 
exists 

status$_bad_process_record 

status$_bad_prc_pub_ 
container 

status$_bad_prcj3riv_ 
container 

status$_bad_process_ 
allocation 

status$_tiiread_name_exists 

status$_bad_thread_record 

status$_bad_thread_ 
allocation 

status$_bad_proc8ss_exit_ 
status 

status$_bad_tliread_exit_ 
status 

status$_quota_exceeded 



the service completed without emsrs 

a specified parameter is not accessable 

a process object already exists with the name 
specified in the process object parameters 

an invalid process record was specified 

the specified process public container can not be 
transfered to the new process 

the specified process private container can not be 
transfered to the new process 

an invalid process allocation list was specified 

a thread object already exists with the name specified 
in the thread object parameters 

an invalid thread record was specified 

an invalid thread allocation list was specified 

an error occured translating the object id of the 
specified process exit status object 

an error occured translating the object id of the 
specified thread exit status object 

not enough quota exists to complete the service 
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os$create_thread 

( 

OUT thread Jd : e$obj'ectJd; 

IN object_parameters : e$obj'ect_parameters = DEFAULT; 

IN threadjprocedure : e$thread_entry_point; 

IN thread_record : e$thread_record = DEFAULT; 

IN thread_allocatlon_list : POINTER e$objectJdJist = NIL; 

IN thread_data_block : POINTER quadword_data(*) CONFORM = NIL; 

IN threadjmmed!ate_parameter1 : POINTER anytype CONFORM = NIL; 

IN threadjmmedlate_parameter2 : POINTER anytype CONFORM = NIL; 

IN thread_status : e$obj'ectJd = DEFAULT; 

) RETURNS STATUS; 

DESCRIPTION Create and additional thread object as specified by the parameters. 



ARGUMENTS 



threadjd 

Returns the object ID of the resulting process object 

object_parameters 

Supplies the object type independent parameters for the thread object the 
ACL and container ID are ignored 

thread_procedure 

Supphes the entrypoint for the new thread 

thread_record 

SuppHes the attributes of the thread being created 

thread_allocation_list 

Supplies the objects to be allocated to the thread object. If not present 
then no objects are allocated to the thread 

thread_data_block 

Supphes an arbitrary data block passed to initial thread. Pointer in TCR, 
if pointer is NIL, then no data block was passed 

thread_immediate_parameter1 

SuppUes an immediate parameter passed to thread through TCR 

thread_immediate_parameter2 

SuppUes an immediate parameter passed to thread through TCR 

thread_status 

SuppHes an exit status object to be bound to the initial thread. If not 
present then the thread is created without an exit status object 
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RETURN ^ u . . u 

\/AIIICO status$_normal the service completed without errors 

status$_access_violatJon a specified parameter is not accessabie 

status$_thr6ad_name_exists a thread object already exists with the name specified 

in the thread object parameters 

status$_bad_thread_record an invalid thread record was specified 

status$_bad_thread_ an invalid thread allocation list was specified 
allocation 

status$_bad_thread_exit_ an error occured translating the object id of the 

status specified thread exit status object 

status$_quota_exceeded not enough quota exists to complete the service 
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os$create_user 

( 

OUTuserJd : e$object_id; 

IN objectjparameters : e$object_parameters = DEFAULT; 

IN user_record : e$user_record; 

IN user_allocatlon_!ist : POINTER e$objectJdJist = NIL; 

IN job_object_parameters : e$object_parameters = DEFAULT; 

INjobjrecord : e$}ob_record = DEFAULT; 

IN job_initial_container : e$object_id = DEFAULT; 

INjob_allocatlonJist : POINTER e$object_ldJist = NIL; 

IN process_object_parameters : e$object_parameters = DEFAULT; 

IN process_record : e$process_record; 

IN process_public_container : e$object_id = DEFA ULT; 

IN process_prlvate_contalner : e$obJectJd= DEFAULT; 

IN process_allocationJist : POINTER e$object_idJlst = NIL; 

IN process_data_block : POINTER quadword_data(*) CONFORM = NIL; 

IN thread_obJect_parameters : e$object_parameters = DEFAULT; 

IN thread_record : e$thread_record = DEFA ULT; 

IN thread_allocationJist : POINTER e$object_ldJlst = NIL; 

IN thread_data_block : POINTER quadword_data(*) CONFORM = NIL; 

IN threadjmmedlate_parameter1 : POINTER anytype CONFORM = NIL; 

IN thread_immediate_parameter2 : POINTER anytype CONFORM = NIL; 

IN thread_status : e$objectJd = DEFAULT; 

) RETURNS STATUS; 

Q£3Qfl[|pi"|ON Create a user, job, process, and thread object as specified by the 

parameters. If the user object collides with an existing user object, then 
use the existing user object. 



ARGUMENTS userjd 

Retiims the object ID of the resulting user object 

object__parameters 

Supplies the object type independent parameters for the user object the 
ACL and container ID are ignored 

user_record 

Supplies the attributes of new user object. 
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user_allocation_list 

Supplies the objects to be allocated to the user object. If not present then 
no objects are edlocated to the user 

job_object__parameters 

Supplies the object type independent parameters for the job object the 
ACL and container ID are ignored 

job_record 

Supplies the attributes of the job being created. If not present, then values 
are obtained from current user object 

job_inniai_container 

SuppHes the job level object container to be transfered into the job level 
container directory for this job. If not present then container directory 
comes up empty 

jobjallocationjist 

Supplies the objects to be allocated to the job object. If not present then no 
objects are allocated to the job 

process_obJectjparameters 

Supplies the object type independent parameters for the process object the 
ACL £ind container ID are ignored 

process_record 

SuppUes the attributes of the process being created 

processjpubllcjcontainer 

SuppUes the process level public container to be transfered into the process 
level container directory for the process. If not present then the container 
comes up empty. 

process_private_container 

Supplies the process level private container to be transfered into the 
process level container directory for the process. If not present then 
container comes up empty. 

process_allocatlon_Ust 

SuppUes the objects to be allocated to the process object. If not present 
then no otgects are allocated to the process 

process_data_block 

SuppUes an arbitrary data block passed to the process 

thread_object_parameters 

SuppUes the object type independent parameters for the thread object the 
ACL and Container ID are ignored 

thread_record 

SuppUes the attributes of the thread being created 

thread_a!Iocation_list 

SuppUes the objects to be allocated to the thread object. If not present 
then no objects are allocated to the thread 
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thread_data_block 

Supplies an arbitrary data block passed to initial thread. Pointer in TCR, 
if pointer is NIL, then no data block was passed 

thread_immediate_parameter1 

Supplies an immediate peirameter passed to thread through TCR 

thread_immediate_parameter2 

Supplies an immediate parameter passed to thread through TCR 

threadjstatus 

Supplies an exit status object to be bound to the initial thread. If not 
present then the thread is created without an exit status object 



RETURN 
VALUES 



status$_normal 

status$_access_violation 

status$_bad_us8r_record 

status$_bad_user_allocation 

status$Job_name_exists 

status$_badJob_record 

status$_badJobJnit_ 
container 

status$_badjob_allocation 

status$_process_name_ 
exists 

status$_bad_process_record 

status$_bad_prc_pub_ 
container 

status$_bad_prc_priv_ 
container 

status$_bad_process_ 
allocation 

status$_thread_name_exists 

status$_bad_tliread_record 

status$_bad_thread_ 
allocation 

status$_bad_process_exit_ 
status 

status$_bad_thr6ad_exit_ 
status 

status$_quota_exceeded 



the sen/Ice completed without errors 

a specified parameter is not accessable 

an invalid user record was specified 

an invalid user allocation list was specified 

a job object already exists with the name specified in 
the job object parameters 

an invalid job record was specified 

the specfied job initial container can not be transfered 
to the new job 

an invalid job allocation list was specified 

a process object already exists with the name 
specified in the process object parameters 

an invalid process record was specified 

the specified process public container can not be 
transfered to the new process 

the specified process private container can not be 
transfered to the new process 

an invalid process allocation list was specified 



a thread object already exists with the name specified 
in the thread object parameters 

an invalid thread record was specified 

an invalid thread allocation list was spedfied 

an error occured translating the object id of the 
specified process exit status object 

an error occured translating the object id of the 
specified thread exit status object 

not enough quota exists to cbmplete the service 
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os$delete_ex[t_hand ler_process 

( 

IN handlerjd : e$exit_hancl!er_id; 
) RETURNS status; 



QggQI^IPI'IQIsJ This service is used to delete an existing process level exit handler. The 

specified exit handler is removed firom the process exit handler list. Once 
an exit handler is delete, it vrill not be processed. 



ARGUIUIENTS 



handlerjd 

Supplies the handler ID of the exit handler to be deleted. 



RETURN 
VALUES 



status$_normal 

status$_exit_handler_not_ 
found 

status$_not_supported 



the service completed without errors 

the handler specified by handlerjd was not found on 
exit handler list 

an attempt to call this service from a system thread 
was made 
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os$delete_exit_hand ler_thread 



( 

IN hancHerJd : e$exit_handler_id; 
) RETURNS status; 



pggQPIpyiQfSj This service is used to delete an existing thread level exit handler. The 

specified exit handler is removed from the threads exit handler list. Once 
an exit handler is deleted, it will not be processed. 



ARGUMENTS handierjd 

Supplies the handler ID of the exit handler to be deleted. 



RETURN 
VALUES 



status$_normal 

status$_exit_handler_not_ 
found 

status$_not_su pported 



the service completed without errors 

the handler specified by handierjd was not found on 
exit handier list 

an attempt to call this service from a system thread 
was made 
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os$exiMhread 

( 

IN exit_status : status; 
) RETURNS status; 

DESCRIPTION '^^ service begins kernel mode esdt processing. This involves calUng all 

thread level exit handlers. The thread object id is then removed. If the 
thread is the last thread in its process, then it executes its process level 
exit handlers. 



ARGUMENTS exit_status 

SuppHes the reason that the thread is exiting 



RETURN 

\/A I I ice status$_repeat_service Seen only by the system service dispatcher. This 

VALUES value is returned when dispatching to an exit handler. 

If the handler returns, os$exit_thread( ) is restarted. 
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os$force_exitJob 

( 

INjobJd : e$objectJd; 
IN exitjstatus : status; 
) RETURNS status; 



DESCRIPTION Force exit the job specified by jobjd. This action causes all of the jobs 

processes to exit 



ARGUMENTS 



job_id 

supplies object id of the job to be exited. 

exit_status 

supplies the reason for job to exit 



RETURN 
VALUES 



status$_normal 
others 



normal completion of the sen/ice 
object id translation errors 
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os$force_exlt_process 



( 

IN processjd : e$objectJd; 
IN exit_status : status; 
) RETURNS status; 



QggQPflPI'IQ^ Force exit the process specified by proces3_id. This action causes all of the 

processes sub-processes and threads to be force exited. 



ARGUI\/1ENTS processjd 

Supplies the object id of the process to be exited. 

exn_status 

SuppUes the reason for the process exiting 



RETURN 
VALUES 



status$_normai 
others 



normal completion of the service 
object id translation errors 
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os$force_exit_thread 

( 

IN threadjd : e$objectJd; 
IN exit_status : status; 
) RETURNS status; 



DESCRIPTION Force exit the thread specified by threadjd. 



ARGUMENTS threadjd 

supplies the object id of the thread to be exited. 

exit_status 

supplies the reason that the thread is force exiting 



RETURN 
VALUES 



status$_normal normal completion of the sen/ice 

others object id translation errors 
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os$force_exit_user 



( 

IN userjd : e$objectJd; 
IN exitjstatus : status; 
) RETURNS status; 



pggQPIpyiON Force exit the user specified by user_obj_id. This action causes all of the 

users jobs to be force exited. 



ARGUMENTS 



userjd 

Supplies the object id of the user to be exited. 

exitjstatus 

Supplies the reason for the user exiting 



RETURN 
VALUES 



status$_normal 
others 



normal completion of the service 
object id translation errors 
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os$get_exit_status_info 

( 

IN exit_statusjd : e$obj'ectJcl = DEFAULT; 
IN exit_statusjtems : POINTER e$ltemjlstjype; 
IN process_status_object : boolean = true; 
) RETURNS status; 



DESCRIPTION 



Return information about the specified exit status. The information 
returned is item list driven 



ARGUMENTS 



exit_status_id 

supplies the object id of the exit status object to get information from. If 
defaulted, then either the process exit status object of the current thread, 
or the thread exit status object of the current thread is assumed. 

extt_status_items 

supplies the item list which specifies the information to be retrieved. 



Code 



e$c_status_value 
e$c_status_string 

e$c_status_string_set 

e$c_status_summary 



Pointer Type 



Action 



status 
varying_string 

boolean 

e$exit_status_summary 



returns the status value from the item list 

returns the status string stored in the exit status 
object 

returns and indication of whether a status string 
exists in the exit status object. True == exists 

returns the exit status summary from the exit 
status object, (this function does not return the 
status string, only its address has no use from 
user mode.) 



process_status_obJect 

only looked at if exits status id is defaulted. If true, the process level exit 
status object of the current thread is assumed, otherwise, the thread level 
exit status is assumed 



RETURN 
VALUES 



status$_normal 

status$_access_violation 

status$_invalid_item_code 

others 



the service completed without errors 

a specified parameter is not accessabie 

a specified item code is invalid, or its item entry is 
invalid 

object id translation errors 
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os$getJob_informatlon 

( 

INjobJd : e$objectJd = DEFAULT; 

IN jobjgetjtems : POINTER e$itemjist_type; 

) RETURNS status; 



QggQPIPTIQI^ Return information about the job object to the caller. The information 

returned is item list driven 



ARGUMENTS 



Code 



e$o_usarJd 
e$c_process_count 

e$c_processJds 

e$c_quota_usage 

e$oJobJimits 

e$cJob_class 



job_id 

supplies if present, the object ID of job object that is to be inspected 
otherwise, the job object of the calling thread is assumed 

Job_get_items 

supplies the item list identifying job object information to be extracted 



Pointer Type 



e$object_id 
integer 

e$objectJd_list 

8$quota_usag9 

e$quota_limits 

e$job_ciass 



Action 



return the object id of tfie jobs user object 

return the number of processes for this user 
(subprocesss not included) 

return the object id's for the users processes 
(subprocesss not included) 

return the jobs resource usage 

return the per job resource limits 

return the job class of the job object 



RETURN 
VALUES 



status$_normal 

status$_access_violation 

status$JnvalidJtem_code 

others 



the service completed without errors 

a specified parameter is not accessable 

a specified item code is invalid, or its item entry is 



invalid 

object id translation errors 
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os$getjprocessJnformation 

( 

IN processjd : e$objectJd = DEFAULT; 

IN processjgetjtems : POINTER e$itemjist_type; 

) RETURNS status; 



DESCRIPTION Return information about the process object to the caller. The information 

returned is item Hst driven 



ARGUMENTS 



process_id 

supplies if present, the object ID of process object that is to be inspected 
otherwise, the process object of the calhng thread is assumed 

process_get_items 

suppHes the item Hst identifying process object information to be extracted 



Code 



e$cJobJd 
a$c_parent_id 

e$c_sub_process_count 
e$c_su b_process_ids 

8$c_thr8ad_oount 

e$c_thread_ids 

e$c_process_accounting 
e$c_pcr_base 
e$c_quota_usage 
e$c_processJim its 



Pointer Type 



e$object_id 
e$objectJd 

integer 
e$object_id_list 

integer 

e$object_idJist 

e$accounting_summary 
e$process_control_region 
e$quota_usage 
e$quota_limits 



Action 



return the object id of tiie processes job 

return tiie object id of the parent process zero() 
if process is not a subprocess 

return the number of sub processes 

return the object id's for the processes sub 
processes 

return the number of threads for the process ( 
threads in sub processes not included) 

return the object ids for the threads of the 
process ( threads in sub processes not included) 

return the process level accounting summary 

return address of the process control region 

return the processes resource usage 

return the per process resource limits 



RETURN 
VALUES 



status$_normal 

status$_access_violation 

status$_invalid_item_code 

others 



the service completed without en-ors 
a specified parameter is not accessable 

a specified item code is invalid, or its item entry is 

invalid 

object id translation errors 
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os$get_threadJnformation 

( 

IN threadjd : e$objectJd = DEFAULT; 

IN thread_getjtems : POINTER e$ltemjist_type; 

) RETURNS status; 



DESCRIPTION 



Return information about the thread object to the caller. The information 
returned is item list driven 



ARGUIVIENTS 



threadjd 

supplies if present, the object ID of thread object that is to be inspected 
otherwise, the thread object of the calling thread is assumed 

thread_get_items 

supplies the item list identifying thread object information to be extracted 



Code 



Pointer Type 



Action 



e$c_process_id 

e$c_tcr_base 

e$c_tiiread_accounting ' 

e$c_thread_perf_counters 

e$c_thread_priority 

e$c_thrBad_affinity 



e$objectJd 

e$thread_control_region 

e$cpu_andJo_summary 

e$tiiread_perf_count8rs 

k$combined_priority 

k$affinity 



returns the object id of the threads process 

returns address of the threads tcr 

returns the thread specific accounting summary 

returns the thread performance counters 

return the current thread priority 

return the current thread affinity 



RETURN 
VALUES 



status$_normal 

status$_access_violation 

status$_invalid_item_code 

others 



the service completed without errors 

a specified parameter is not accessable 

a specified item code is invalid, or its item entry Is 
invalid 

object Id translation errors 
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os$get_userJnfornnation 

( 

IN userjd : e$obj'ectJd = DEFAULT; 

IN user_getjtems : POINTER e$ltemjist_type; 

) RETURNS status; 



QggQPIpjION Return information about the user object to the caller. The information 

returned is item list driven 



ARGUMENTS 



user_id 

supplies if present, the object ID of user object that is to be inspected 
otherwise, the user object of the calling thread is assumed 

userjgetjtems 

supplies the item Ust identifying user object information to be extracted 



Code 



Pointer Type 



Action 



e$cJob_count 


integer 


return the number of jobs for tiiis user 




e$cJobJds 


8$object_idJist 


return the object id's for the users jobs 




e$c_username 


varying_string 


return the user name 




e$c_quota_usage 


s$quota_usage 


return the users resource usage 




8$c_user_limits 


e$quota limits 


return the users resource limits 




a$cJobJimits 


e$quotaJimits 


return the per job resource limits 




e$c__process_limits 
e$c_thread_priority 
e$c_thread_affinity 


e$quotaJimits 

k$combined_priority 

k$affinity 


return the per process resource limits 
return the default thread priority 
return the default thread affinity 




e$c_access_restrictions 


e$acc8SS_restrictions 


return the access retrictions 




RETURN 
VALUES 


status$_normal 


the sen/ice completed without errors 





status$_access_violation 
status$_invalidJtem_code 

others 



a specified item code is invalid, or its item entry Is 

invalid 

object id translation errors 
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os$h ibernate_process 

( 

IN processjd : e$object_icl; 
) RETURNS status; 



DESCRIPTION Cause all threads owned by the process specified by process_id to issue a 

wait on the auto-clearing hibernate event object in their TCB. User mode 
ASTs remain enabled 



ARGUMENTS processjd 

supplies the object of the target process 



RETURN 

_^ statusS normal the service completed without errors 

VALUES 

status$_access_violation a specified parameter is not accessable 

status$_quota_exceeded not enough quota exists to capture the thread or 

subprocess ids of the specified process 

others object id translation errors 
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os$hibernate_thread 

( 

IN thread Jd : e$objectJd; 
) RETURNS status; 



DESCRIPTION Cause the thread specified by threadjd to issue a wait on the auto- 
clearing hibernate event object in its TCB. User mode ASTs remain 
enabled 



ARGUMENTS threadjd 

supplies the object of the target thread 



RETURN 

.....1.^ status$ normal the service completed without errors 

VALUES 

status$_acoess_violation a specified parameter is not accessable 

others object id translation errors 
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os$resume_process 

( 

IN processjd : e$object_id; 
) RETURNS status; 



Qj^gQPIpyiON Cause all threads owned by the process specified by process objectjd to 

have their waits on the auto-clearii^ suspend event object in their TCB to 
be satisfied by setting the event. 



ARGUMENTS processjd 

supplies the object ID of the target process 



\/AIIICC status$_normal the service completed without errors 

status$_access_vioiation a specified parameter is not accessabie 

status$_quota_exceeded not enough quota exists to capture the thread or 

subprocess ids of the specified process 

others object id translation errors 
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os$resume__thread 

( 

IN threadjd : e$objectJd; 
) RETURNS status; 



QESCRIPTION Cause the thread specified by thread object_id to have its wait on the 

auto-clearing suspend event object in its TCB to be satisfied by setting the 
event. 



ARGUMENTS threadjd 

supplies the object ID of the target thread 



RETURN 

status$_normal the service completed without errors 

status$_access_violation a specified parameter is not aocessable 

others object id translation errors 
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os$set exit statusjnfo 



( 

IN exit_statusjd : e$objectJd = DEFAULT; 
IN exit_statusjtems : POINTER e$item_list_type; 
IN process_status_object : boolean = true; 
) RETURNS status; 



DESCRIPTION 



Set information in the specified exit status. The information returned is 
item list driven 



ARGUMENTS 



Code 



e$c_status_string 



exit_status_!d 

supplies the object id of the exit status object to set information into. If 
defaulted, then either the process exit status object of the current thread, 
or the thread exit status object of the current thread is assumed. When 
this id is defaulted, then the process or thread level exit status object is 
used by address (no acl protection) since we assume that you can always 
write to your own exit status object. 

exit_status_items 

supplies the item list which specifies the information to be set. 



Pointer lype 



Action 



varying_string 



places the specified string in tine exit status 
object 



process_status_obJect 

only looked at if exits status id is defaulted. If true, the process level exit 
status object of the current thread is assumed, otherwise, the thread level 
exit status is assumed 



RETURN 
VALUES 



status$_normal 

status$_access_violation 

status$_invalidJtem_code 

others 



the service completed without errors 

a specified parameter is not accessable 

a specified item code is invalid, or its Item entry is 
invalid 

object Id translation errors 
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os$setJobJnformatlon 

( 

INjobJd : e$objectJd = DEFAULT; 

IN job_setJtems : POINTER e$itemjist_type; 

) RETURNS status; 



Q£3Qp|py|0N Return information about the job object to the caller. The information 

returned is item list driven 



ARGUMENTS 



Jobjd 

suppHes if present, the object ID of job object that is to be modified 
otherwise, the job object of the calling thread is assvraied 

Job_set_items 

supplies the item Kst identifying job object information to be modified 



Code 



e$cJobJimits 



Pointer Type 



Action 



e$quota_limits 



set the per job resource limits 



RETURN 
VALUES 



status$_normal 

status$_access_violation 

status$JnvaiidJtem_code 

others 



the service completed without errors 

a specified parameter is not accessable 

a specified item code is invalid, or its item entry is 
invalid 

object id translation errors 
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os$set_minor_thread__priority 

( 

IN threadjd : e$objectJd = DEFAULT; 
IN newjf)riority : k$minor_priority; 
OUT previous_priority : k$combined_priority; 
) RETURNS status; 



nPCQRIPTION '^^^ system service changes the minor priority of the specified thread. 



ARGUMENTS 



threadjd 

Supplies the object id of the thread whose priority is to be altered. If this 
parameter is defaulted, the current thread is assumed 

new_pnority 

Supplies the minor priority that is to be set in the specified thread. 

previous_pnonty 

Returns the specified threads previous combined priority. Only valid if 
status$_normal was returned. 



RETURN 
VALUES 



status$_normal the service completed without errors 

status$Jnvalid_argument newjsriorlty is not a valid value for k$minor_priority 

others object id translation errors 
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os$set__processJnformat[on 

( 

IN processjd : e$objectJd = DEFAULT; 

IN process_setJtems : POINTER e$itemjist_type; 

) RETURNS status; 



pggQPJpyiQ^ Return information about the process object to the caller. The information 

returned is item Kst driven 



ARGUMENTS 



Code 



e$c_protected_data 



e$c__processJim its 



process_id 

supplies if present, the object ID of process object that is to be modified 
otherwise, the process object of the calling thread is assumed 

process_setJtems 

suppUes the item list identifying process object information to be modified 



Pointer Type 



anytype 



e$quotaJimits 



Action 



add block to protected data listhead in ihe per 
(item lengtli determines how many bytes of data 
are being linl<ed to tlie list.) 

replace the per process resource timits 



RETURN 
VALUES 



status$_normal 

status$_access_violation 

status$JnvalldJtem_code 

others 



the service completed without errors 

a specified parameter is not accessable 

a specified item code is invalid, or its item entry is 

invalid 

object id translation errors 
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os$set_threadJnformation 

( 

IN threadjd : e$objectJd = DEFAULT; 

IN thread_setjtems : POINTER e$ltemjist_type; 

) RETURNS status; 



DESCRIPTION 



Return information about tlie thread object to the caller. The information 
returned is item list driven 



ARGUMENTS 



threadjd 

supplies if present, the object ID of thread object that is to be modified 
otherwise, the thread object of the calling thread is assumed 

thread_set_items 

supplies the item list identifying thread object information to be modified 



Code 



Pointer Type 



Action 



e$c_tiiread_priority 
e$c_thread_mnr_priority 
e$c_thr8ad_mjr_priority 
e$c_thread_affinity 



k$combined_priority 
k$minor_priority 
k$nnajor_priority 
k$affinity 



set tiie current tiiread priority 
set tlie current thread minor priority 
set the currant thread major priority 
set the current thread affinity 



RETURN 
VALUES 



status$_normal 

status$_access_violation 

status$JnvalidJt6m_code 

others 



the service completed without errors 

a specified parameter is not accessable 

a specified item code is invalid, or its item entry is 
invalid 

object id translation errors 
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os$set__thread_prlority 

( 

IN threadjd : e$objectJd = DEFAULT; 
IN new_prlority : k$combined_priorlty = 0; 
OUT previousjpriority : k$combined_priority; 
) RETURNS status; 

DESCRIPTION T^s system service changes the combined priority of the specified thread. 



ARGUMENTS 



threadjd 

Supplies the object id of the thread whose priority is to be altered. If this 
parameter is defaulted, the current thread is assximed 

newjpriority 

SuppUes the combined priority that is to be set in the thread. If this 
parameter is defaulted, the base priority of the threads process is assumed. 
If the major priority in new_priority is greater than the threads current 
major priority, then the calHng thread must have access to the raise 
priority privileged operation object. 

This service never allows the priority to be changed out of the priority 
class that the thread process is a member of. If the prbcess is not in a 
realtime priority class, then the threads priority can not be changed to a 
realtime priority dass. If the process is within a realtime priority class, 
then the threads new priority must stay within a realtime priorily class. 

prev!ous_priority 

Returns the specified threads previous combined priority. Only valid if 
status$_normal was returned. 



RETURN 
VALUES 



status$_normal 
status$_invalid_argument 

others 



the service completed without errors 

new_priority Is not a valid value for k$combined_ 
priority, or specifies a priority class that is different 
from the threads process 

object id translation errors 
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os$set_userJnfornnatlon 

( 

IN userjd : e$objectJd = DEFAULT; 

IN user_set_items : POINTER e$item_list_type; 

) RETURNS status; 



DESCRIPTION 



Return information about the user object to the caller. The information 
returned is item list driven 



ARGUMENTS 



userjd 

supplies if present, the object ID of user object that is to be modified 
otherwise, the user object of the calling thread is assumed 

user_set_items 

supplies the item list identifying user object information to be modified 



Code 



e$c_userjimits 

e$cJob_limits • 

e$c_process_limits 

e$c_thread_priority 

e$c_thread_affinity 

e$c_aocess_restrictions 



Pointer Type 



Action 



e$quotaJimits 

e$quotaJimits 

e$quota_limits 

k$combined_priority 

k$affinity 

e$access_restrictions 



set the users resource limits 
set the per job resource limits 
set the per process resource limits 
set the default thread priority 
set the default thread affinity 
set the access retrictions 



RETURN 
VALUES 



status$_normal 

status$_access_violation 

status$JnvaIid_ltem_code 

others 



the sen/ice completed without errors 

a specified parameter is not accessable 

a specified item code is invalid, or its item entry is 
invalid 

object id translation errors 
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os$signal__process 

( 

IN processjd : e$object_id; 

IN condition_value : status; 

IN signal_argument : longword CONFORM = DEFAULT; 

) RETURNS status; 



DESCRIPTION 



Cause a condition of type condition_value to be raised in all threads owned 
by the process specified by proce3s_id. The condition handler is passed 
signal_argmnent. 



ARGUMENTS 



process_id 

supplies the object_id of the process to be signaled 

condition_vaIue 

supplies a condition value to be raised in all threads of the target process 

signal_argument 

supplies the value that is passed to the condition handler 



RETURN 
VALUES 



status$_normal 

status$_access_violation 

others 



the service completed without errors 
a specified parameter is not accessable 
object id translation errors 
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os$signaLthread 

( 

IN threadjd : e$object_id; 

IN condition_value : status; 

IN signal_argument : longword CONFORM = DEFAULT; 

) RETURNS status; 



Q£3CRIPTI0N Cause a condition of type condition_value to be raised in the thread 

specified by thread_id. The condition handler is passed signal_argument. 



ARGUMENTS 



thread_id 

suppHes the object_id of the thread to be signaled 

condition_value 

supplies a condition value to be raised in all threads of the target thread 

signaljargument 

suppHes the value that is passed to the condition handler 



RETURN 
VALUES 



status$_normal 
status$_access_violation 
status$_not_supported 
others 



the service completed without errors 
a specified parameter is not accessabie 
the target thread was a system thread 
object id translation errors 
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os$suspend_process 

( 

IN processjd : e$object_id; 
) RETURNS status; 

Ql^gQPIpyiQ^ Cause all threads owned by the process specified by process_id to issue a 

wait on the auto-cleaiing suspend event object in their TCB. User mode 
AST's are disabled. 



ARGUI\AENTS processjd 

supplies the object ID of the target process 



RETURN , , , ..... 

traiiir-<^ status$_normal the service completed without errors 

VALUES 

status$_access_violation a specified parameter is not accessabie 

status$_quota_exceeded not enough quota exists to capture the thread or 

subprocess ids of the specified process 

others object id translation errors 
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os$suspend_thread 



( 

IN threadjd : e$objectJd; 
) RETURNS status; 



DESCRIPTION Cause the thread specified by threadjd to issue a wait on the auto- 
clearing suspend event object in its TCB. User mode AST's are disabled. 



ARGUMENTS threadjd 

supplies the object ID of the target thread 



RETURN 
VALUES 



status$_normal 

status$_access_vioiation 

others 



the service completed without errors 
'a specified parameter is not aocessable 
object Id translation errors 
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os$wake_process 

( 

IN processjd : e$objectJd; 
) RETURNS status; 

DESCRIPTION Cause all threads owned by the process specified by process_id to have 

their waits on the auto-cleaiing hibernate event object in their TCB to be 
satisfied by setting the event. 



ARGUMENTS processjd 

supplies the object ID of the target process 



RETURN , , , , 

\/A I I ice status$_normal the service completed without errors 

status$_acoess_violation a specified parameter is not accessable 

status$_quota_exceeded not enough quota exists to capture the thread or 

subprocess ids of the specified process 

others object id translation errors 
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os$wake_thread 

( 

IN threadjd : e$object_id; 
) RETURNS status; 



QPgQpipyiQI^ Cause the thread specified by threadjd to have its wait on the auto- 
clearing hibernate event object in its TCB to be satisfied by setting the 
event. 



ARGUMENTS threadjd 

supplies the object ID of the target thread 



RETURN 
VALUES 



status$_normal 

status$_access_violation 

others 



the service completed without errors 
a specified parameter is not accessable 
object id translation errors 



7-44 



Q Memory System Services 



8-1 



DIGITAL - Confidential and Proprietary - Restricted Distribution 
os$adjust_working_set_limit 



os$adjust_workmg_set_limit 

( 

IN number_of_bytes : integer; 

OUT new_working_set_limit : integer [1..]; 

) RETURNS STATUS; 



DESCRIPTION 



The Adjust Working Set Limit service adjusts a process's current working 
set limit by the specified number of bytes and returns the new value to the 
caller. The specified number of bytes will be converted into pages and the 
calculated number of pages will be added to or removed from the working 
set. A negative value for the byte count will cause pages to be removed 
from the working set. 



ARGUMENTS 



number_of_bytes 

SuppHes the number of bytes to add or remove firom the working set. 

new_working_set_/imit 

Returns the current size of the working set in bytes. The working set is 
maintained in pages and converted to bytes. 



RETURN 
VALUES 



status$_normal 
status$Jnvalid_address 

status$_working_set_at_ 
maximum 

status$_working_set_at_ 
minimum 



normal, successful completion. 

error, either the starting or ending address is not 
accessable. 

error, unable to add any more pages to the working 
set. 

error, unable to. remove any more pages from the 
working set. 
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os$create_address_space 

( 

IN desired_beginning_adclress : POINTER anytype CONFORM; 
IN desired_ending_address : POINTER anytype CONFORM; 
OUT actual_beginning_address : POINTER anytype CONFORM; 
OUT actual_ending_address : POINTER anytype CONFORM; 
) RETURNS status; 



DESCRIPTION 



This routine creates address space at the specified address. An error is 
returned if any of the desired address range is already mapped, but the 
create address will map from the desired address up to the already created 
addresses, and that range will be returned. 



ARGUMENTS 



desired_beginn!ng_address 

Supplies the beginning address of the range to create. 

desired_ending_address 

Supplies the ending address of the range to create. 

actual_beginnmg_address 

Returned address of the beginning of the range actually created. The 
actual range could differ from the desired range due to 64K byte 
alignment. 

actual_ending_address 

Returned address of the ending of the range actually created. 



RETURN 
VALUES 



status$_normal 

status$_invalid_begin_ 
address 

statusS invalid ending 
address 

status$_compiete_range_ 
not_map 



normal, successful completion. 

error, the beginning address is invalid. 

error, the ending address is invalid. 

warning, the complete range of addresses could not 
be mapped do to previously mapped addresses. 
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os$create_section 

( 

OUT sectionjd : e$obJect_id; 

IN object_j)arameters : e$object_parameters = DEFAULT; 

IN file_channel : integer OPTIONAL; !### needs fixed also item list needs to 

be added 

IN mappingjtype : e$mapping_type OPTIONAL; 

IN size_in_bytes : integer OPTIONAL; 

IN virtual_block_number : integer OPTIONAL; 

IN protection : e$page_protection OPTIONAL; 

IN identification_matcii : integer OPTIONAL; 

) RETURNS status; 



DESCRIPTION 



This routine creates a section which is either backed by an existing file or 
backed by paging file. 



ARGUMENTS 



sectionjd 

Returned object ID of the created section. 

object^parameters 

Supplies the object container in which the object is inserted, the name of 
the object, and the access control Ust (ACL) of the object. If this argument 
is not supplied or if it is supplied but not all values in the object parameter 
record are supplied, the service applies default values. The default object 
container is the process private container, the default name is none, and 
the default ACL is none, to map the section into. 

file_channel 

Supplies the object ID of a previously created channel which has had a file 
open performed. If the channel is not supplied, a section backed by paging 
file is created. 

mappingjtype 

SuppHes the type of section to create, either data or image. 

sizejn_bytes 

Supplies the size of the section to create in bytes. If page file mapping is 
performed this paraimeter is required. 

virtual_biocl(_number 

Supplies the virtual block number offset within the opened file to begin 
mapping. This virtual block number is aligned on a 64K byte boundary. 
Hence is the virtual block nimaber is specified as 40 the actual virtual 
block number woiild be 33 (start at vbn 1). 
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protection 

Supplies the desired protection to apply to the newly created pages, 
optional. 

!dentification_match 

Supplies the id to match, optional. 



RETURN 
VALUES 



status$_normal 
status$Jnvalid_address 

status$_mapping_conflict 

status$Jnvalid_section_size 

status$_requires_channel_ 
arg 

others 



normal, successful completion. 

error, either the starting or ending address is not 
accessable... 

error, the specified address range contains pages 
which are already mapped. 

error, the size specified for the section is invalid. 

error, the section type requires a channel to be 
specified. 

any object error in creating an object. 
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os$delete__address__space 

( 

IN desirecl_beginning_address : POINTER anytype CONFORM; 
IN desired_endlng_address : POINTER anytype CONFORM; 
OUT actual_beginning_address : POINTER anytype CONFORM; 
OUT actual_endlng_address : POINTER anytype CONFORM; 
) RETURNS status; 



DESCRIPTION 



This routine deletes the address space at the specified address. An 
warning status is returned if any of the desired address range is mapped 
in by a mapping object, i.e. was not created by e$create_virtual_address_ 
space and only the address space up to the found address is deleted. 



ARGUMENTS 



desired_beginning address 

Supplies the beginning ad3ress of the range to delete. 

desired_ending_address 

Supplies the ending address of the range to delete. 

actual_beginning_address 

Returned address of the beggin of the range actually deleted. The actuEil 
range could differ from the desired range due to 64K byte alignment. 

actual_ending_address 

Returned address of the ending of the range actually deleted. 



RETURN 
VALUES 



status$_normal 

status$jnvalicl_begin_ 
address 

status$Jnvalid_endingL 
address 

status$_total_range_not_ 
deleted 



normal, successful completion. 

error, the beginning address is invalid. 

error, the ending address is invalid. 

warning, the complete range of addresses could not 
be deleted do to previously mapped addresses. 
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os$expancl_address_space 



( 



IN number_of_bytes : integer [0. .]; 

OUT actual_beginning_address : POINTER anytype CONFORM; 
OUT actual_end}ng_acldress : POINTER anytype CONFORM; 
) RETURNS status; 



DESCRIPTION 



This routine creates address space starting at the highest virtual address 
in use by the process for the number of bytes specified. 



ARGUMENTS 



number_of_bytes 

Supplies the number of bytes to add to the address space. 

actual_beginning_address 

Returned address of the first byte of the created address range. 

actual_ending_address 

Returned address of the last byte of the created address range. 



RETURN 
VALUES 



status$_normal 

status$_complete_range_ 
not_map 



normal, successful completion. 

warning, the complete range of addresses could not 
be mapped do to previously mapped addresses. 
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os$expand_user_stack 

( 

IN number_of_bytes_to_add : integer [1..]; 
OUT new_stack_size : integer [1..]; 
) RETURNS STATUS; 



DESCRIPTION 



The Expand User Stack service attempts to adjust the user stack by the 
specified number of bytes. The number of bytes is converted into pages 
and an attempt is made to expand the stack by the calculated number of 
pages. 

The stack expansion miay fail due to other thead user stacks occupying 
virtual address space and thereby preventing the stack expansion. Note 
that there is no way to contract a stack. 



ARGUMENTS 



number_of_bytes_to_add 

SuppUes the number of bytes to add to the stack. The number of bytes is 
converted to pages. 

newjstackjsize 

Returns the current stack size in bs^tes. 



RETURN 
VALUES 



status$_normai 

status$_unabla_to_expand_ 
stack 

status$_partial_expansion 

status$_invalid_address 



normal, successful completion, 
error, stack expansion failed. 

warning, not all bytes were added to the stack. 

error, either the starting or ending address is not 
accessable. 
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os$get_mapplng_lnformation 

r 

IN mappingjd : e$ob}ectJd; 

IN mappingjgetjtems : POINTER e$itemjist_type; 

) RETURNS STATUS; 



Q|ggQP|p*|"|Q^ The Get Mapping Information service provides information about the 

specified mapping object. The information which may be obtained is 
specified in an item list. 



ARGUMENTS 



mappingjd 

Supplies the object ID of the desired mapping object on which information 
should be extracted. 

mappingjgetjtems 

Supplies the item Ust which specifies the information about the mapping 
object to return. 



Item code 



description 



e$c_mapping_s8Ction 



e$c_mapping_starting_ 
address 



e$c_mapping_si2e 
e$c_mapping_offset 



The object ID of the section 
which this mapping object 
maps. 

The starting address of the 
mapping in the address 
space. 

The size of the mapping in 
bytes. 

The byte offset from the start 
of the section object. 



RETURN 
VALUES 



status$_normal 
object_reference_errors 



normal, successful completion. 

any errors trying to reference an object by id. 
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os$get_sectionJnformatlon 

( 

IN sectionjd : e$object_id; 

IN sectionjgetjtems : POINTER e$itemjist_type ; 

) RETURNS STATUS; 



QESC¥(\PT\Qtii "^^ ^* Section Information service provides infonnalion about the 

specified section object. The information which may be obtained is 
specified in an item list. 



ARGUMENTS 



sectionjd 

SuppUes the object ID of the desired section on which information should 
be extracted. 

sectionjgetjtems 

SuppUes the item list which specifies the information about the section to 
return. 

The following codes are valid: 



item code 



action 



e$c_section_vbn Virtual block number offset 

which the section is based 
upon. 

e$c_section_size Size of the section in bytes. 

e$c_section_protection_code Protection code assigned to 

section pages. 

e$c_section_ident_match Identification match specified 

on section. 

e$c_section_type Type of section (image or 

data). 



RETURN 
VALUES 



status$_normal 
object_reference_errors 



normal, successful completion. 

any errors trying to reference an object by id. 
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os$lock__pagesJn__memory 

IN starting_address : POINTER anytype CONFORM; 
IN ending_address : POINTER anytype CONFORM; 
OUTIastJocked_address : POINTER anytype CONFORM; 
) RETURNS STATUS; 



DESCRIPTION 



The Lock Pages in Memory service locks a page or range of pages in 
memory. The specified virtual pages are forced into the working set, 
then locked in memory. A locked page is not removed from memory if its 
process's working set is removed from the balance set. 



ARGUMENTS 



starting_address 

Supplies the starting virtual address of the range to be locked into 
memory. 

ending__address 

Supplies the ending virtual address of the the range to be locked into 
memory. 

lastJocked__address 

Returns the last address which was actually locked in memory. 



RETURN 
VALUES 



status$_normal 

status$_com plete_range_ 
notjock 

status$JockedJimit_reachecl 

status$Jnvalid_address 



normal, successful completion. 

warning, at least one page was locked in memory. 

error, no more pages may be locked in memory. 

error, either the starting or ending address is not 
accassable. 
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os$lockj3ages_worklng_set 



IN starting_address : POINTER anytype CONFORM; 
IN ending_address : POINTER anytype CONFORM; 
OUT lastJocked_address : POINTER anytype CONFORM; 
) RETURNS STATUS; 



DESCRIPTION '^® ^'^^ pages in working set service locks a page or range of pages in 

a process's working set. The specified virtual pages are forced into the 
working set. 



ARGUMENTS 



startmg_address 

Supplies the starting virtual address of the range to be locked into the 
working set. 

ending_address 

Supplies the ending virtual address of the the range to be locked into the 
working set. 

lastJocked_address 

Returns the last address which was actually locked in the working set. 



RETURN 
VALUES 



status$_normaJ 
status$_complete_range_ 
notjock 
status$_workingL.set_full 

status$_invalid_address 



normal, successful compietion. 

warning, at least one page was locked in the working 

set. 

error, no more pages may be locked in the working 

set. 

error, either the starting or ending address is not 

accessable. 
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os$map_section 



( 



OUT mappingjd : e$objectJd; 

IN objectjparameters : e$object_parameters = DEFAULT; 

IN sectionjd : e$objectJd; 

IN deslred_beginnlng_address : POINTER anytype CONFORM 

OPTIONAL; 

IN deslred_endlng_address : POINTER anytype CONFORM OPTIONAL; 

IN protection : e$page_protectlon OPTIONAL; 

IN identification_match : integer OPTIONAL; 

IN byte_offset : integer [0..] OPTIONAL; 

OUT actual_beginning_address : POINTER anytype CONFORM; 

OUT actual_ending_address : POINTER anytype CONFORM; 

) RETURNS status; 



DESCRIPTION 



This routine maps a previously created section into the process's address 
space. 



ARGUMENTS 



mappingjd 

Returned object ID of the mapping object which describes the memory 
section. 

object_parameters 

Supplies the object container in which the object is inserted, the name of 
the object, and the access control list (ACL) of the object. If this argument 
is not supplied or if it is supphed but not all values in the object parameter 
record are supphed, the service appUes default values. The defavdt object 
container is the process private container, the default name is none, and 
the default ACL is none. 

sectionjd 

SuppHes the object ID of previously created section. 

desired_beginning_address 

SuppUes the beginning address of the range to map the section into. The 
range must not currently have any vaHd addresses. The actual mapping 
occurs on a 64K bjrtes boundary. 

desired_end!ng_address 

SuppUes the ending address of the range to map the section into. 

protection 

SuppUes the desired protection to apply to the newly created pages, 
optional. 
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identificatlon_match 

Supplies the id to match, optional. 

byte_offset 

Supplies the offset into the section to beginning mapping, optional. 

actual_beginning_address 

Retixms the actual beginning address of the created range. 

actual_ending__address 

Returns the actual ending address of the created range. 



RETURN 
VALUES 



status$_normal 
status$Jnvalid_address 

status$_mapping_conflict 

status$Jnvalid_map_ 
container 

others 



normal, successful completion. 

error, either the starting or ending address is not 
accessable. 

error, the specified address range contains pages 
which are already mapped. 

error, the specified container for the mapping object 
was not the default private container. 

any object error in creating an object. 
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os$set_j3rotection_on_pages 

( 

IN starting_address : POINTER anytype CONFORM; 

IN encling_address .'POINTER anytype CONFORM; 

IN page_protection : e$page_protection; 

OUT last_changed_address : POINTER anytype CONFORM; 

OUT previous__page_protection : e$page__protectlon OPTIONAL; 

) RETURNS status; 



DESCRIPTION 



The Set Protection on Pages system service allows a thread to change the 
protection on a page or range of pages. 



ARGUMENTS 



starting_address 

Supplies the starting virtual address of the range to have its protection 
modified. 

endmg_address 

Supplies the ending virtual address of the the range to have its protection 
modified. 

page_protection 

Supplies the page protection to assign to the pages within the specified 
address range. The page protection is a set with the following members. 
Note that write impUes read and for user access, kernel access is always 
set to be identicad. Also, user execute or kernel execute implies the other. 



protection code 



protection 



e$c_page_user_read 

e$c_page_user_write 

e$c_pag8_user_exscute 

e$c_page_kernel_read 

e$c_page_kemei_writa 

e$c_page_l<ernel_execute 



user read access, 
user write.read access, 
user execute access, 
kemei read access, 
kernel write access, 
kernel execute access. 



last_changed_address 

Returns the last address which the protection was actually changed. 

previous_page_protection 

Optionally returns the previous page protection for the first page which 
the protection was actually changed. 
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RETURN 
VALUES 



status$_normal 
status$_partial_range_done 

status$_invalid_argum8nt 

status$_invalidj3rotection 

status$_page_owner_ 
violation 



normal, sucessfui completion. 

warning, unable to change the protection on the 
complete range do to nonexistant pages. 

error, unable to access or iterpret argument. 

error, protection set contains invalid members. 

error, attempt to change kernel protection on kernel 
owned pages. 
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os$unIock_pages_from_memory 

( 

IN startlng_address : POINTER anytype CONFORM; 
IN ending_adclress : POINTER anytype CONFORM; 
OUT last_unlocked_address : POINTER anytype CONFORM; 
) RETURNS STATUS; 



DESCRIPTION "^^ unlock pages from memory service unlocks a page or range of pages 

from memory. The specified virtual pages are unlocked from memory and 
become eligible for replacement. 



ARGUMENTS 



starting_address 

Supplies the starting virtual address of the range to be unlocked from 
memory. 

endmg_address 

Supplies the ending virtual address of the the range to be unlocked from 
memory. 

lastjockedjaddress 

Returns the last address which was actually unlocked from memory. 



RETURN 
VALUES 



status$_nornial 

status$_complete_range_ 
notjock 

status$ invalid address 



nonmcil, successful completion. 

warning, at least one page was unlocked from 
memory. 

error, either the. starting or ending address is not 
accessabie. 
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os$unlock_pages_working_set 

( 

IN starting_address : POINTER anytype CONFORM; 
IN ending_aclclress : POINTER anytype CONFORM; 
OUT last_unlocked_address : POINTER anytype CONFORM; 
) RETURNS STATUS; 



DESCRIPTION '^^ unlock pages firom working set service unlocks a page or range 

of pages &t)m a process's working set. The specified virtual pages are 
unlocked from the working set and become eligible for replacement. 



ARGUiVIENTS 



starting_address 

Supplies the starting virttial address of the range to be unlocked from the 
working set. 

endingjaddress 

Supplies the ending virtual address of the the range to be unlocked from 
the working set. 

last_locked_address 

Returns the last address which was actually unlocked from the working 

set. 



RETURN 
VALUES 



status$_normal 

status$_complete_range_ 
notjock 

status$Jnvalid_adclress 



normal, successful completion. 

warning, at least one page was unlocked in the 
working set. 

error, either the starting or ending address is not 
accessable. 
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os$update__mapped_section 

( 

IN mappingjd : e$objectJd; 

IN clesired_beginning_address : POINTER anytype CONFORM; 

IN desired_ending_address : POINTER anytype CONFORM; 

IN flags : e$section_update_flags; 

IN eventjd : e$objectJd OPTIONAL; 

IN astjprocedure : k$normal_ast__routine OPTIONAL; 

IN ast_parameter : LONGWORD CONFORM OPTIONAL; 

BIND iojstatusjblock : e$losb; 

OUT actual_beglnnlng_address : POINTER anytype CONFORM; 

OUT actual_ending__address : POINTER anytype CONFORM; 

) RETURNS STATUS; 



DESCRIPTION 



The Update Mapped Section service writes all modified pages in a mapped 
section back into the section file on disk. One or more I/O requests are 
queued based on the nimiber of pages that have been modified. 



ARGUMENTS 



mappingjd 

Supplies the mapping ID of the mapped section to update. 

desired_beginning_address 

Optionally supplies the beginning address within the mapping to begin 
updating the section. If this argument is not specified, the starting address 
of the mapping will be used. 

desired_ending_address 

Optionally supplies the ending address within the mapping to end 
updating the section. If this argument is not specified, the endinng 
address of the mapping will be used. 

flags 

Optionally supplies the update specified for updating the section. More 
here later. 

event_id 

Optionally supplies the object ID of an event object which will be set when 
the update operation has completed. 

ast_procedure 

optionally supphes the address of an AST procedure which will be called 
when the update operation has completed. 

ast_parameter 

Optionally supples the value which will be suppHed to the AST procedure 
when called. 
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io_status_block 

Optionally supplies the I/O status block which will receive the final 
completion status of the updating operation. 

actual_begmning_address 

Optionally returns the actual beginning address of the update operation. 

actual_end!ng_address 

Optionally returns the actual ending address of the update operation. 



RETURN 

MAI I iPQ status$_normal normal, sucessful completion. 

status$_invalid_address_ error, beginning or ending address was not within the 

range mapping as specified by the mapping ID. 

object_raference_errors any errors trying to reference an object by id. 
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os$zero_to_end_of_user_stack 

( 

) RETURNS STATUS; 



Q|£3CRIPTI0N '^® ^'**' ^ T^^d of User Stack service zeroes all pages from the current 

stack pointer to the end of the stack. The zeroing is accomplished 
by releasing any pages in physical memory or in the paging file and 
converting the pages into demand zero pages. 



ARGUMENTS None. 



RETURN 

irai • ii-j^ status$ norma! normal, successful completion. 

VALUES 
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os$canceMo 

( 

IN channeljd : e$object_id; 
) RETURNS status; 



DESCRIPTION 



This service cancels all outstanding I/O request on the spediied channel. 
Only the outstanding I/O requests that were issued by the calling thread 
are canceled. 

Outstanding I/O requests that are canceled are done so, asynchronously to 
the the completion of the this service. That is, completion of this service 
cannot be used to synchronize with the cancellation of the I/O requests. 



ARGUMENTS 



channeljd 

Supplies an ID of the channel 



RETURN 
VALUES 



status$_normal 

status$Jnvalid_objectJd 

status$_object_type_ 
mismatch 



normal, successful completion, 
invalid object id 
invalid object 
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os$configure_fp 



( 



IN fpdjd : e$object_id; 

IN function_code : integer; 

IN userjevent : e$object_id = DEFAULT; 

IN fpd_parameters : POINTER anytype CONFORM = DEFAULT; 

) RETURNS status; 



DESCRIPTION 



This service is used to issue configuration and deconfiguration requests to 
a function processor. The function code and the fpd_parameters specifies 
the reqeust type. 

The user supplied event object is specified if the caller wants to 
s3mchronized with the completion of the request. 



ARGUMENTS 



fpdJd 

Supplies the FPD object ID 

function_code 

Supplies the configuration function code 

user_event 

Supplies object id of event to be signalled when done 

fpd_parameters 

Supplies the FPD configuration parameters. 



RETURN 
VALUES 



status$_normal 

status$_invalid_abject_id 

status$_object_type_ 
mismatch 



normal, successful completion 
invalid object id 
invalid object 
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os$create_channel 

( 

OUT Chan neljd: e$object_icl; 

IN object_parameters : e$object_parameters; 

IN fpujd : e$obJect_id; 

) RETURNS status; 



DESCRIPTION 



This service is call to create a channel to an existing FPU object. The 
FPU object ID parameter specifies the FPU object to which the channel is 
attach. 

The object ID of the newly created channel is returned in the channel_ 
id parameter. After the channel object is created it is inserted into the 
container specified in the object_paranieters record. If there is a duplicate 
object currently in the container, the newly created channel object is 
deleted, and the object ID of the duplicate object is returned. If a container 
object ID is not specified, the channel object is placed in the process private 
container. 



ARGUMENTS 



channeled 

Returns a chemnel id 

object_parameters 

Supplies the object architecture create object parameters 

fpu_id 

SuppUes an object id of the FPU object to create a channel to 



RETURN 
VALUES 



status$_normal 

status$_invalid_obJ6ct_id 

status$_duplicate_object 

status$_object_contianer_full 

status$_object_type_ 
mismatch 



normal, successful completion 

invalid object id 

duplicate object found in abject container 

object container full 

invalid object 
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os$create_Jpu 



( 



OUTfpuJd: e$objectJd; 

IN object_parameters : e$object_parameters; 

IN fpdjd : e$objectJd; 

INfpujparameters : POINTER anytype CONFORM = DEFAULT; 

) RETURNS status; 



DESCRIPTION 



This service creates an FPU object for a function processor. The ^d_id 
parameter specifies the function processor for which the FPU object is 
created for. 

The object ID of the newly created FPU object is returned in the fpu_id 
parameter. The object parameters specifies the object name, an ACL for 
the FPU object, and the object ID of the container where the FPU object is 
to be inserted in. 

If a container object ID is not supplied, the FPU object is inserted into the 
process private container after it is created. If a duplicate object already 
exist in the specified container, the newly created FPU object is deleted, 
and the object ID of the duplicate object is returned 



ARGUMENTS 



fpu_id 

Return the objisct id of the created FPU object. 

oblect_paramters 

Supplies the object parameters. 

fpdJd 

Supplies the object id of fpd. 

fpu_parameters 

Supplies the FPU specific parameters used to initialize the the FPU object. 



RETURN 
VALUES 



status$_normal 
status$Jnvalid_obiGct_id 
status$_du plicate_object 
status$_object_CQntainGr_full 



normal, successful completion 

invalid object 

duplicate object found in object container 

object container full 
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os$get_channelJnformation 

( 

IN channeljd : e$object_id; 

IN channeljtems : POINTER e$ltemjist_type = DEFAULT; 

) RETURNS status; 



DESCRIPTION Returns information about a channel object. The information returned is 

item list driven. 



ARGUMENTS 



channel_id 

Supplies channel object ID. 

channeljtems 

Supplies a pointer to an item list. 



Item Codes 



Data Type 



Description 



io$oJtem_chiannel_access 
io$cJtem_granted_aocess 



BOOLEAN 
SET[accass_type] 



TRUE, If channel is being access. 

Returns the access types that have been granted 
on this channel. 



RETURN 
VALUES 



status$_normed 

status$Jnvalld_object_id 

status$_object_type_ 
mismatch 



normal, successful completion 
invalid object id 
invalid object 
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os$get__fpuJnformation 

( 

IN fpujd : e$objectJd; 

IN fpujtems : POINTER e$item_list_type = DEFAULT; 

) RETURNS status; 



DEgQRIPTION Returns information about an FPU object. The information returned is 

item list driven. 



ARGUMENTS 



fpu_id 

Supplies an FPU object ID. 

fpujtems 

Supplies a pointer to an item list. 



Item Codes 


Data Type 


Description 


io$cJtem_interface_class 


INTEGER 


Returns FPU interface class 


io$cJtem_fpu_state 


e$fpu_state 


FPU current state 


io$c_fpu_bour»cl 


Integer 


Returns TRUE if FPU is bound 


io$c item fp_params area 
size 


Integer 


Returns size of the FP parameter area needed 
by this function processor and all function 
processor below it. The size is returned in 
quadwords. 





RETURN 
VALUES 



status$_normal 

status$Jnvalid_objectJd 

status$_object_type_ 
mismatch 



normal, successful completion 
invalid object ID 
invalid object 
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os$requestJo 

( 

IN channeljd : e$object_id; 

IN function_code : integer; 

BIND iosb : e$iosb; 

IN completion_event_id : e$obJect_id = DEFAULT; 

IN completion_ast : k$normal_ast_routine = DEFAULT; 

IN ast_parameter : POINTER anytype CONFORM = DEFAULT; 

IN io_parameters : POINTER anytype CONFORM = DEFAULT; 

) RETURNS status; 



DESCRIPTION 



This service is used to issue an I/O request. Two types of I/O request may 
be issued, they are: 

a. Asynchronous I/O request, and 

b. Synchronous I/O request 

An I/O request is describe by its function code and I/O parameter record 
supplied to this service. The request will fail if the channel or event object 
is invalid, the function code or I/O parameters are invalid. The returned 
status will contain the cause of failxnre. No information will be written to 
the I/O status block. 

An asynchronous I/O request is issued if an event object, AST procedure, 
or both are specified ia the call. Control is return to the caller after 
the request has been successfully posted. When the I/O completes, the 
following events can occtir: 

a. If an event object was specified, it is signalled. 

b. If an AST procedure was specified, the AST is queued to the calling 
thread. 

c. If both event object and a AST procedure is specified, the event is signal 
first, then the AST is queued. 

In the absents of an event object or an AST procedure, will cause the 
request to be synchronous. In the case of a sjmchronous I/O request, the 
calling thread is not allow to continue until the request completes. 

The I/O request completion status is returned in the I/O status block. 



ARGUMENTS 
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channeled 

Supplies the object id of channel to request io on 

function_code 

Supplies an I/O request function code 

iosb 

Supplies an I/O status block 
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compietion_event_id 

Supplies a user event object to be signaled after I/O the completes 

completion_ast 

Supplies an ast procedure address to be calledwhen the I/O completes. 

ast_parameter 

Supplies a parameter for an ast procedure 

io_parameters 

Supplies a pointer to an I/O parameter record 



RETURN 
VALUES 



status$_normal 

status$_invalid_object_id 

status$_wrong_record_type 

status$_object_type_ 
mismatch 

status_wrong_device_oiass 



nomiai, successful completion 

invalid objectjd 

incorrect I/O parameter record for this function code. 

Invalid object 

Invalid function code for this device. 
Interface class specific status 
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os$synchronize_with_io 



( 

IN eventjd : e$object_id; 
BIND iosb : e$iosb; 
) RETURNS status; 



DESCRIPTION 



This service sjrachronize the calling thread with a ciirrently outstanding 
asynchronous I/O request. 

This service can only be use for asynchronous request that contians at 
least an event object. 

The event object and the IOSB of the previously issued asynchronous I/O 
request must be supplied as the parameters to this service. 



ARGUMENTS 



iosb 

SuppBes an IOSB. 

event_id 

Supplies an event object ID. 



RETURN 
VALUES 



status$_normal 

status$_invalid_objectJd 

status$_object_typ8_ 
mismatch 



normal, successful completion 
invalid object id 
invalid object 
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os$synch_channe[_wlth_fpu 

( 

IN channel Jd : e$object_id; 
) RETURNS status; 



Q|£3CRIPTION This routines synchronizes the channel with an FPU object. This is done 

by copying the sequence number in the FPU object to the channel object. 



ARGUMENTS channeljd 

Supplies a object id of the channel object to be synchronized. 



RETURN 
VALUES 



status$_normal 

status$_invalid_object_id 

status$_object_type_ 
mismatch 



normal, successful completion 
invalid object id 
invalid object 
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os$createJmpersonation 

( 

OUT impersonation_id : e$object_id; 

IN objectjDarameters : e$object_parameters = DEFAULT; 

IN remote_noclename : string (*); 

IN remote_username : string (*); 

IN password: string (*) OPTIONAL; 

) RETURNS status; 



DESCRIPTION 



The os$create_iinpersonation service allows user mode servers to create an 
impersonation object. The impersonation object can then be used as input 
to the os$impersonate_client service to impersonate remote clients. 

This service verifies that the remote user is a valid user of the system by 
requesting the remote user's local user authorization record. If a record 
exists and the specified password, if any, matches the password in the 
authorization record, the user is a valid user of the system. If the user is 
a valid user, the service creates the impersonation object representing the 
remote user fi-om the remote user's local user authorization record. 

The object_parameters parameter is a record consisting of a name, an 
object container ID, and an ACL. This record, and values for these fields, 
are optionally provided by the caUer. The nsune field is the name of the 
object. If a value is not supplied, the object is created vrithout a name. 
The object container ID field identifies the object container into which the 
object is inserted, but this field is ignored; the object is inserted into the 
process-private container. The ACL field supplies additional protection for 
the object. If a value is not suppHed, the object is created vdthout an ACL. 

Note: The only server calling this service should be the DFS server. 



ARGUMENTS 



impersonation_id 

Returns the object id of the created impersonation object. 

object_parameters 

Supphes the object's name, object container, and protection. 

remotejnodename 

Supphes the name of the remote node. 

remote_username 

Supplies the name of the remote user. 

password 

Supphes the password specified by the remote user. 
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RETURN 
VALUES 



status$_normal 
status$_duplicate_object 
status$_obj8ct_container_full 
status$Jnvalid_user 

status$Jnvalidj3assword 



normal, successful completion. 

duplicate object found in object container. 

object container full. . 

the specified user is not authorized to access the 
system. 

the specified password was not valid. 
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os$create_priv_operatlon 

( 

OUT privileged_operation_id : e$object_id; 

IN object_parameters : e$object_parameters = DEFAULT; 

) RETURNS status; 



DESCRIPTION 



The os$create_priv_operation creates a privileged operation object. A 
privileged operation object represents a privileged operation. This object 
allows software that performs a privileged operation, to determine if a 
user can perform the privileged operation. If the user has PERFORM_ 
OPERATION access to the privileged operation object, the user is allowed 
to perform the privileged operation. 

Software can have multiple privileged operation objects; the name of each 
privileged operation object denotes the privileged operation. 

The object_parameters parameter is a record consisting of a name, an 
object container ID, and an ACL. This record, and values for these fields, 
are optionally provided by the caller. The name field is the name of the 
object. A value must be supplied because it specifies the name of the 
privileged operation. The object container ID field identifies the object 
cont^ner into which the object is inserted, but this field is ignored; the 
object is inserted into the exec$privileged_operation_container system-level 
container. The ACL field supplies additional protection for the object. If a 
value is not supplied, the object is created vrithout an ACL. 



ARGUMENTS 



privUeged_operatlon_id 

Returns the object id of the created privileged operation object. 

object_parameters 

Supplies the object's name, object container, and protection. 



RETURN 
VALUES 



status$_normal 
status$_duplicate_object 
status$_object_container_f u II 



normal, successful completion, 
duplicate object found in object container, 
object container full. 
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os$deIete_access__controlJist 

( 

IN objectjd : e$object_id; 
) RETURNS status; 



DESCRIPTION Th6 os$delete_access_coiitrol_list services deletes the specified object's 

access control list. 



ARGUMENTS objectjd 

Supplies the object id of the object whose ACL is deleted. 



RETURN 
VALUES 



status$_normai normal, successful completion. 

status$_invalid_objectJd invalid object id. 
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os$disable_identifier 



( 

IN identifier : e$identifier; 
) RETURNS status; 



DESCRIPTION 



The os$enable_identifier service disables an identifier in the caller's user 
identifier list. After the identifier is disabled, it is not used by the system 
when determining access to objects. - 

The caller must hold the specified identifier before it can be disabled. 

The identifier miist have the dynamic attribute in order to be disabled. 



ARGUMENTS 



identifier 

SuppUes the identifier to disable. 



RETURN 
VALUES 



status$_normal 

status$Jdentifier_not_found 

status$Jdent_already_ 
disabled 

status$Jdentifier_not_ 
dynamic 



normal, successful completion. 

the identifier was not found in the user identifier list. 

the identifier was already disabled. 

the identifier does not have the dynamic attribute. 
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os$enableJdentifier 

( 

IN identifier : e$identifier; 
) RETURNS status; 



DESCRIPTION 



The os$eiiable_identiiier service enables eui identifier in the caller's user 
identifier list. After the identifier is enabled, it is used by the system when 
determining access to objects. 

The caller must hold the specified identifier before it can be enabled. 

The identifier must have the dynamic attribute in order to be enabled. 



ARGUMENTS 



Identifier 

SuppUes the identifier to enable. 



RETURN 
VALUES 



status$_normal 

status$_identifier_not_found 

status$Jdent_already_ 
enabled 

status$Jdentifier_not_ 
dynamic 



normal, successful completion. 

the identifier was not found in the user identifier list. 

the identifier was already enabled. 

the identifier does not have the dynamic attribute. 
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os$get_access_controMist 

( 

IN objectjd : e$object_id; 

IN acl : POINTER e$access_controlJlst; 

) RETURNS status; 



DESCRIPTION 



The os$get_acce3s_control_list service returns the specified object's access 
control list. 

When the service is called, it copies the object's ACL into the ACL pointed 
to by the ACL parameter. The memory specified by the ACL parameter is 
managed by the caller and must be large enough to hold the object's ACL. 
If the ACL is not large enough, the service copies as many entries as the 
ACL can hold and returns an error status. 



ARGUMENTS 



objectjd 

Supplies the object id of the object whose ACL is returned. 

acl 

Supplies a pointer to the ACL into which a copy of the object's ACL is 
written. The memory containing the ACL is managed by the caller. 



RETURN 
VALUES 



status$_normai 

status$_invalid_objact_id 

status$_acljengtfi_too_small 



normal, successful completion. 

invalid object id. 

the size of the specified ACL was not large enough 
to hold the object's ACL. 



10-8 



DIGITAL - Confidential and Proprietary - Restricted Distribution 

os$get_security_monltor 



os$get_securlty_monitor 

( 

OUT security_events_enabled : SET e$security_event [..]; 
) RETURNS status; 



QESCRIPTION The os$get_sectirity_inonitor service returns a summary of the security 

events that Eire being monitored. 



ARGUMENTS security_events_enabled 

Returns the summary of security events that are being monitored. 



RETURN 

\/A I I ICC status$_normai normal, successful completion. 
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os$impersonate_ciient 

( 

IN impersonationjd : e$object_id; 

IN identifier_optlon : e$imp_identifier_option; 

) RETURNS status; 



DESCRIPTION 



The os$iinpersonate_client service allows a server to impersonate a client. 
A server can restore its own identity by calling the os$restore_server 
service. 

The only context of a client that can be impersonated are the identifiers 
held by the client. The server can specify to the service how to 
impersonate the client's identifiers. If the server wants to impersonate the 
client only, the service sets the caller's identifier Hst to the list contained 
in the impersonation object. If the server wants to impersonate the union 
of the client and the server, the service allocates pool, combines the caller's 
identifier list and the identifier list in the impersonation object and saves 
the resultant list in the pool, and sets the caller's identifier list to the hst 
contained in the pool. 

Before the service performs the impersonation, it restores the caller's 
previous identifier hst. This allows the caller to impersonate multiple 
clients in succession without having to make an explicit call to the 
os$restore_server service. 

When a server impersonates a cUent, the server can access objects as if it 
were the cHent. 



ARGUMENTS 



impersonationjd 

SuppUes the object id of the impersonation object. 

identifier_option 

Supplies how the service perfonns the impersonation. If e$c_cUent_ 
identifiers value is specified, the service sets the server's identifiers to the 
client's identifiers in the impersonation object. If the e$c_union_identifiers 
value is specified, the service combines the server's identifiers with the 
cKent's identifiers in the impersonation object. 



RETURN 
VALUES 



status$_normal 

status$_invalid_object_id 

status$_object_type_ 
mismatch 



normal, successful completion. 

invalid object id. 

the object identified by the imersonation id is not an 
impersonation object. 
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os$restore_server 

( 
); 



P|^3CR1PT10N Th^ os$restore_server service restores a server's original identifier list. 

This service is used by servers that call the os$impersonate_client service 
to impersonate clients. 



ARGUMENTS None. 



RETURN 

VALUES ^°"" 
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os$set_access_control_l ist 



( 

IN objectjd : e$object_id; 

IN acl : POINTER e$access_controlJist; 

) RETURNS status; 



QE5CRIPTION '^® os$set_access_control_list sets the specified object's access control list. 

The memory specified by the ACL parameter is managed by the caller. 
When the service is called, it allocates pool and copies the contents of the 
specified ACL into the pool. 



ARGUMENTS 



object_id 

Supplies the object id of the object whose ACL is set. 

ad 

Supplies a pointer to the ACL from which the ACL on the object is set. 
The memory containing the ACL is managed by the caller. 



RETURN 
VALUES 



status$_normal 
status$Jnvalid_objectJd 
status$Jnvalid_acl 
status$_invalid_ac8 



normal, successful completion, 
invalid object id. 
invalid ACL. 
invalid ACE. 
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os$set__security__monitor 

( 

IN security_events_enabled : SET e$security_event [..]; 
IN security_events_dlsabled : SET e$security_event [..]; 
) RETURNS status; 



P£3QP|P'P|Q|S| The os$set_security_monitor enables or disables the monitoring of security 

events. 



ARGUMENTS 



securlty_events_enabled 

Supplies the stnnmary of security events indicating the security events to 
start monitoring. 

security_events_disabled 

Supplies the summary of security events indicating the security events to 
stop monitoring. 



RETURN 
VALUES 



status$_normal 



normal, successful completion. 



10-13 



DIGITAL - Confidential and Proprietary 
os$translate_access_type 



Restricted Distribution 



os$translate__access_type 

( 

IN accessjype : e$access_type; 

IN objectJype_name : string (*) OPTIONAL; 

OUT access_type_name : string (*); 

) RETURNS status; 



DESCRIPTION 



The 03$translate_acceas_type service translates an access tj^re to its 
corresponding access type name. 

The access type can be either a general or specific access type. If the 
access type is a general access type, the caller does not have to specify the 
object_type_name parameter. If the access t3rpe is a specific access type, 
the caller must specify the object_type_name parameter. The object type 
name denotes the object type that defined the specific access type. 

The service performs a case sensitive search to match the object type 
name. 



ARGUMENTS 



RETURN 
VALUES 



access_type 

Supplies the access type to translate. 

obJect_type_name 

Supplies the object type name of the object type that defined the specific 
access type. 

access_type_name 

Returns the access type name corresponding to the access type. 



status$_normal 
status$Jnvalid_access_type 
status$Jnvalid_name_length 
status$Jnvalid_obiect_type 



normal, successful completion. 

invalid access type. 

length of the object type name was not valid. 

invalid object type specified by the object type name. 
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os$translate_access_type_name 

( 

IN access_type_name : string (*); 

IN obJect_type_name : string (*) OPTIONAL; 

OUT access_type : e$access_type; 

) RETURNS status; 



DESCRIPTION 



The os$traiislate_access_1ype_name service translates an access type name 
to its corresponding access type. 

The access type name can correspond to either a general or specific access 
tjrpe. If the access type name corresponds to a general access tjrpe, the 
caller does not have to specify the object_type_name parameter. If the 
access type name corresponds to a specific access type, the caller must 
specify the object_type_name parameter. The object type name denotes the 
object type that defined the specific access type. 

The service performs a case sensitive search to match the access type 
name and object type name. 



ARGUMENTS 



access_type_name 

Supplies the access type name to translate. 

object_type_name 

SuppUes the object type name of the object type that defined the specific 
access type. 

access_type 

Returns the access type corresponding to the access type name. 



RETURN ^ ^, , 

l/Al I lEC status$_normal normal, succassful completion. 

status$_lnvallcl_namejength length of the access type name or the object type 

name was not valid. 

status$_lnvalicl_access_type invalid access type specified by the access type 

name. 

status$Jnvalid_object_type invalid object type specified by the object type name. 
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os$verify_j>rlv__operation 

{ 

IN privileged_operation_id : e$object_id; 
) RETURNS status; 



DESCRIPTION The os$verify_priv_operation allows software to determine if a user can 

perform the privileged operation represented by the specified privileged 
operation object. If the user has PERFORM_OPERATION access to the 
privileged operation object, the user is allowed to perform the privieged 
operation. 



ARG UM ENTS pnvUeged_operation_id 

Supplies the object id of the privileged operation object. 



RETURN 

VAI I iCC status$_normal normal, successful completion. 

status$Jnvalid_object_id invalid object id. 

status$_object_type_ the abject identified by the privileged operation id is 

mismatch not a privileged operation object. 
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os$create_condition_stack 

( 

IN condition_stack_size : integer[0..]; 
) RETURNS status; 

P£3CRIPTI0N "^^^ system service creates a condition stack of the specified size. If a 

condition stack already exists, then a new stack is not created and an 
error status is retumed. The stacks size is based on the requested size 
parameter and is always rounded up two a system defined value. A single 
guard page is placed at the top of the stack. 



ARGUMENTS condition_stack_size 

Supplies the size in bytes for the condition stack being created. This value 
is always rounded up to an appropriate graniilarity. 



RETURN . , . 

\/AI I ice status$_normal Normal succesful completion of the system service 

status$_no_user_stack_va The condition stack was not created because no 

virtual address space in the stack region could be 
found large to staisfy the request. 

status$_condition_stadt_ A new condition stack was not created since a 

exists condition stack already exists. 
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os$createJast_chance_hand ler 

( 

IN condition_handler : e$conditlon_hand!er; 
OUT handlerjd : e$condition_handlerJd; 
) RETURNS status; 



DESCRIPTION 



This system service creates a last chance vectored condition handler. Last 
chance vectored condition handlers are processed in LIFO order during 
condition delivery. This service places the created last chance handler at 
the beginning of the last chance vectored condition handler list stored in 
the calling threads TCR. The service returns a resulting handlerjd which 
may be used to delete a last chance vectored condition handler once it has 
been created. 

The condition handler is linked on the hst head in the calling threads TCR 
indexed by the processor mode that the call was made in. 



ARGUMENTS 



conditlonjhandler 

Supplies the condition handler routine to be invoked when a condition is 
being dispatched. 

handlerjd 

Returns the handler ID of the created last chance handler. This argument 
is only vaHd if the service returns statiis$_normal. 



RETURN 
VALUES 



status$_normal 
status$ access violation 



the service completed without errors 
a specified parameter is not accessible 
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os$createj3rimary__handler 

( 

IN condition_hand!er : e$condition_handler; 
OUT handlerjd : e$condition_handlerJd; 
) RETURNS status; 



DESCRIPTION 



This system service creates a primary vectored condition handler. Primary 
vectored condition handlers are processed in FIFO order during condition 
delivery. This service places the created primary handler at the end of the 
primary vectored condition handler list stored in the calling threads TCR. 
The service returns a resulting handler_id which may be used to delete a 
primary vectored condition handler once it has been created. 

The condition handler is linked on the list head in the calling threads TCR 
indexed by the processor mode that the call vsras made in. 



ARGUMENTS 



condit!on_handler 

Supplies the condition handler routine to be invoked when a condition is 
being dispatched. 

handler_id 

Returns the handler ID of the created primary handler. This argument is 
only valid if the service returns status$_normal. 



RETURN 
VALUES 



status$_normal 
status$_access_vio lation 



the service completed without errors 
a specified parameter is not accessible 
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os$deleteJast_chance__handier 

( 

IN handlerjd : e$condition_handler_id; 
) RETURNS status; 



DESCRIPTION 



This service deletes an existing last cliance vectored condition handler. 
Once deleted, the condition handler vrill not be called during exception 
dispatching. 

The condition handler is deleted from the list head in the calling threads 
TCR indexed by the processor mode that the call was made in. 



ARGUIVIENTS 



handler_id 

Supplies the handler id of the last chance vectored condition handler 
which is to be deleted. 



RETURN 
VALUES 



status$_normal 

status$_condifion_handl8r_ 
not found 



the service completed without errors 

the last chance vectored condition handler specified 
by handierjd was not found. 
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os$deletejprimary_handler 



( 

IN handlerjd : e$condition_hancller_id; 
) RETURNS status; 



DESCRIPTION 



This service deletes an existing primary vectored condition handler. 
Once deleted, the condition handler will not be called during exception 
dispatching. 

The condition handler is deleted from the list head in the calling threads 
TCR indexed by the processor mode that the call was made in. 



ARGUMENTS handlerjd 

Supplies the handler id of the primary vectored condition handler which is 
to be deleted. 



RETURN 
VALUES 



status$_normal the service completed without errors 

status$_condition_handler_ the primary vectored condition handier specified by. 
not found handier id was not found. 
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os$get_performanceJnfo 

IN datajist: POINTER e$itemjist_type; 

IN componentjist: POINTER e$ltemjist_type = NIL; 

) RETURNS status; 



DESCRIPTION Return requested information about the usage of Mica system resources. 



ARGUMENTS 



RETURN 
VALUES 



Supplies the address of an item Ust which describes the data items to be 
gathered. 

componentjist . , . . v * « 

Supplies the address of the data.Hst item Hst. If the data_hst speafies 
date items for a component class, this Ust specifies the components for 
which data is to be gathered. If the component item hst is not specified, or 
does not include any components of the requested type then information 
is returned for all components of the requested type. If the component.hst 
includes component types for which data is not requested, those component 
types are ignored. 



status$_normal 
status$_no_xxx_com ponent 

status$_xxx_buffer_overflaw 
status$_access_violatian 



All data was gathered (success) 

A specified component of type xxx is missing from 

the system. Data was returned for all other specified 

components of that type, (success) 

The data buffer for item xxx was not large enough to 

hold the requested data (failure) 

The service cannot access the locations specified by 

one or more items (failure) 
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os$get_system_information 



os$get__systemJnformation 

( 

IN system_jget_items : POINTER e$item_list_type; 
) RETURNS STATUS; 



QE3CRIPTI0N "^^ ^* System Information system services returns information about 

the current system. 



ARGUMENTS 



systemjgetjtems 

Supplies the item list which specifies the information about the system to 
return. The following codes are valid: 



item code 



action 



e$c_syi_boottime 

e$c_syi_cpu_type 

e$c_syi_software_version 

e$c_syi_number_pagefiies 

e$c_syi_pagefiie_free 

e$c_syi_pagefile_ussd 

e$c_number_of_scalar_cpus 

e$c_number_of_vector_cpus 

e$c_memory_size 

e$c_freej3agejist_size 

e$c_zeroed_page_list_size 

e$c_modified_pageJist_size 

e$c_standby_page_list_size 

e$c_bad jDageJ ist_size 



Returns the time wtien the 
system was booted. 

Returns the CPU processor 
type. 

Returns the current version 
of the operating system. 

Returns the current number 
of pagefiies installed. 

Returns the total number of 
free pages in all pagefiies. 

Returns the total number of 
used pages in all pagefiies. 

Returns the total number of 
scalar processors. 

Returns the total number of 
vector processors. 

Returns the amount of 
memory on the system. 

Returns the size of the free 
page list. 

Returns the size of the 
zeroed page list. 

Returns the size of the 
modifed page list. 

Returns the size of the 
standby page list. 

Returns the size of the bad 
page list. 



RETURN 
VALUES 
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status$_normal Nqrmal,successful completion. 

stauts$Jnvaiici_item_code error, invalid item code found. 
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os$get_system_time 



os$get_system_t[me 

( 

OUT system_time : e$binary_absolute_time; 
) RETURNS STATUS; 



pggQPIpyiQ^ The Get System Time service returns the ciirrent time in ISO time format. 



ARGUMENTS systemjtime 

Returns the current time. 



RETURN 
VALUES 



status$_normal Success, normal completion. 

status$_invalid_argument Error, cannot access argument. 
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os$get_uid 

i 

IN desired_number : integer [1..] = 1; 

OUT first_uid : e$uid; 

OUT number_allocated : integer [0..] OPTIONAL; 

) RETURNS STATUS; 



DESCRIPTION 



The G«t UID (Unique Identifier) service returns a UID for use in various 
components of the Digital Network Architecture. 



ARGUMENTS 



desired_number 

Optionally supplies the desired number of UIDs to allocate. This allows 
a single call to reserve a group of UIDs for usage. If this argximent is not 
supplied an allocation group of one is returned. 

firstjuid 

Retiuns the first unique identifier in the allocated group. 

number_aIlocated 

Returns the number of UIDs reserved. 



RETURN 
VALUES 



status$_normal 

status$Jnvalid_argument 

status$_not_all_created 



Success, normal completion. 

Error, cannot access argument. 

Warning, the desired number of UIDs could not be 
created. 
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os$install_page_fiie 



os$instali_page_file 

( 

IN page_file_name : string (*); 
) RETURNS STATUS; 



DESCRIPTION "^^ Install Page Pile service installs the specified file as a paging file. The 

specified file must already exist and not be currently accessed. 



ARGUMENTS page_file_name 

Supplies the file name of the spedfed page file to install. 



RETURN 
VALUES 



status$_normal 
file access errors 



Normal, suces'sful completion, 
whatever. 
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os$next__uid 

( 

IN previousjuld : e$uid; 
OUT nextjjid : e$uid; 
) RETURNS STATUS; 



DESCRIPTION "^^ Next UID (Unique Identifier) service returns a the next UID in a 

created UID range. 



ARGUMENTS 



f)revious_uid 
applies the previous UID in the range yrhich vras returned. 

nextjuid 

Returns the next UID. 



RETURN 
VALUES 



status$_normal 
status$_invalid_uid 



Success, normal completion. 

Error, the value for the UID was not a valid UID. 
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os$set_system_time 



os$set_system_time 

( 

IN system_time : e$binary_absolute_time; 
) RETURNS STATUS; 



DESCRIPTION "^^ S®* System Time service changes the value of the system time. 



ARGUMENTS system_time 

Supplies the new time value for the system time. 



RETURN 
VALUES 



status$_normal 

status$Jnvalid_argument 

status$_no_rights 



Success, normal completion. 

Error, cannot access argument. 

Error, the thread does not have the proper identifier 
to change the system time. 
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A.1 



Executive Constants 



5 

I Executive Defined Cotiatants 

T 

io$c_deacces9 = -1; 1 

io$c_fpu_acce3a = -2; ! 

io$o_get_£pu_infonnation - -3; 
io$c_get_channol_inforniation = 
lo$c_establish_callback = -5; 
i.o$a enable_state change_asli » 
io$c_disable_3tate_chango_a3t = 
ioSc_itom_intorfaco_class = -1; 
io$e_itein_fpu_3tate = -2; 
lo$a itein_fpu_bound • -3; 
io$c_iteni_fp_parain3_area_aize — 
io$c_itoni_channel_accoa3 = -1; 
lo$c Item granted acceaa = -2; 
io$c access request_io : 
i.o$c accoss_get_chn_info 
io$c_access_management ; 
lo$a acceas maintenance : 
io$c_acce33_pexformance : 
io$c_acce3s_diagno8tic : 
io$c_acce33_allow_channel 
lo$c acceas get £pu info 
io$c access accounting 



(e$regueat_io, e$execute_io, e$synchronous_io) 
(e$regue3t_io) 

! (e$reguest_io) 
-4; ! (e$regue3t_io) 

! (e$3ynchronous_io_call) 
-6; ! (a$request io, e$aynchronous io call) 
-7; ! (o$roque3t_io, e$synchronou3_io_call) 



-4; 



e$acc«33_t3^pe - 

e $ acce a a_type 

e$acce3s type = 



e$c_3pecif ic_aoco33_l ; 
= e$c_specific_acces3_2; 
e$c specific access 1; 
e$acce33_type = a$c_3pecific_acc633_2; 
e$acco33_type = e$c_3pecif ic_acce3s_3; 
e$access type = e$c specific access 4; 
: e$accea3_type = e$c_specific_aGce3s_5; 
e$acces3 type = e$c specific access 6; 



o$accaa8_type = a$c_specific_acce33_7; 
io$c_acce3a_acces3 : e$acce33_type •■ e$c_specific_acoo33_8; 
io$c_acoosa_£pu_read : e$acce3a_type = o$c_specif io_aGce3s_9; 
io$c_acc»sa_fpu_write : e$access_type = e$c_3poci£ic_acoess_10; 
e$c ea max string — 32767; 
e$a_max_image_nams = 256; 
e$G_max_name = 255; 
e$G max eqvnam count = 128; 

obj$a_max_objeGt_namo =« 127; !# This should be 255. 
e$c_max_ace_count = 255; 
e$c max user name = 32; 
k$c_high_priority_level = 63; 
k$c_high_proce3aor_nuitiber = 31; 
e$G_max_aco_identifier_count = 63; 
e$c max audit name = 246; ! Specified by ACL Architecture. 



A.2 Miscellaneous Data Types 



Misceleneous Data Types 
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o$binary_aboolute_time : RECORD 
utc_value : large_integer; 
Inaccura^ : integer [0..] SIZE (BIT, 32); 



reserved : integer [0. 
tdf : integer [ -720.. 
version : integer [0., 
LAYOUT 

utc_vaXue; 

inaccuracy; 

reserved; 

tdf; 

version; 
END LAYOUT; 
END RECORD; 



Unique Identifier Format 



e$uid : RECORD 

first_quadword : 
3econd_ciuadword 

END RECORD; 



.2**16 - 1] SIZE (BIT,16); 

780] SIZE (BIT, 12); 
2**4 - 1] SIZE (BIT, 4); 



!!!*** sil limitation should be 48 bits 
! ! ! *** sil limitation . . . 



large_integer; 
1 argo_integer ; 



Common Item List Format 



e$item_list_type(ilv_max_entries : integer ) : RECORD 

CAPTURE ilv_max_entrie3; 

ilv_la3t_inuse_entry : integer; 

ilv_direction : e$item_li3t_direction; 

ilv_list : ARRAY [1 . .ilv_max_entries] OF e$item_liat_entry; 
END RECORD; 



max size number of entries 
! index of last valid entry 
! direction of entire item list 



e$item list direction 



( e$o_item_list_in_out, 
e$c_item_list_in, 
e$c item list out 



); 



An Item List Consists of an array of item list entries 



e$item_list_entry : 
ile_item code : 
ile_item_length 

ile item address 



RECORD 
integer; 
: integer; 

: POINTER anytype; 



ile return length address 
LAYOUT 

ile item code ; 

ile_item_length ; 

ile_item_address ; 

ile return length address 
END LAYOUT; , 



POINTER integer; 



internal format of an item code 
internal format of an item length 
item address 
address of return length 



END RECORD; 



Common Linked List Entry/Header 



e$linked list 
l_flink : 
l_blink : 

END RECORD; 



: RECORD 

POINTER e$linked_list; 
POINTER e$linked list; 



Wait Type 
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e$wait_type : ( 
«$c_wait_any, 
e$c_wait_all 

); 

k$proces3orjnode : (k$c_kernel, k$c_uaer) ; 
AST Procedure Format 



k$nonnal_a3t_routine : 
PROCEDOEE ( 

IN context : POINTER amytype CONFORM; 
IN aystemjvalue : quadword CONFORM; 

); 



A.3 I/O Data Types 



I/O status Block 



e$ioab : RECORD 

condition value : longword; 

byte_count : longword; 

fp_condition : quadword; 
END RECORD; 



! I/O status 
I/O transfer count 
! Filled in by the FP. 



e$fpu_state : (io$c_fpu_state_o£fline, io$c_fpu_state_available, 
io$c_fpu_3tate_online, io$c_£pu_stato_tranaition, 
. xo$c_fpu_3tate_inaintenance) ; 



A.4 Logical Name Data Types 



e$logical_naine_list (length : integer [1..]) = RECORD 
CAPTURE length; 
la3t_valid_entry : integer; 
context : large_integer; 

logical_name : ARRAY [1.. length] OF varying_string (e$a_max_naine) ; 
LAYOUT 

length; 

la3t_valid_entry; 

context ; 

logioal_naine; 
END LAYOUT; 
END RECORD; 

e$equivalence_naino_li3t (length : integer [1 . . e$c_max_eqvnam_count] ) : RECORD 
CAPTURE length; 
laat_valid_entry : integer; 
context : large integer; 

equivalence_najne : ARRAY [1.. length] OF varYing_3tring (e$c_niax_name) ; 
LAYOUT 

length; 

la3t_valid_entry; 

context ; 

equivalence name; 
END LAYOUT; 
END RECORD; 

e$lognam_attribute3 : ( 

e$c_confine lognam attr, 
e$c_noalia3_lognain._attr, 
e$c_noahow_lognain_attr 

); 



A-3 



Executive Constants and Data Types 



|V.5 Memory Management Data Types 



e$pa9e_pzo'bec'tion3 



( 
e$ c_^ago_uaer_read, 
e$c_page user wcite, 
e$o_page_usor_exocute, 
a $ c_page_kemel_raad , 
e$ c_jpage_kemel_Mrite , 
e$c_paga_kemel execute) ; 



e$iiiapping_type : (e$c_data_map, o$c_imago_map) ; 
e$page_protection : SET e$page_protoction3 [ . . ] ; 
e$section_update_flaga : integer; i ! ! *** fix this 



A.6 Process Architecture Data Types 



Process Accounting Summary 

The final accounting record contains this information in TLV format 
in addition to fields identifying the process, image name, user . . , 



e$accounting_summary : RECORD 

acct_total_page_faults : integer; 

acct_hard_page_fault3 : integer; 

acct_3oft_page_faults : integer; 

acct_dzro_page_faulta : integer; 

acct_com_page_faults ; integer; 

acct_peak_virtual_memory : integer; 

acct_peak_working_3et_aize : integer; 

acct_3tart_time : large integer; 

acct_end_time : large_integer; 

acct_page_file_usage : integer; 

acct_pagad_pool_u3age : integer; 

acct_non_paged_pool_usage : integer; 

acct_cpu and_io : e$cpu_and io sutmnary; 
END RECORD; ~ ~ 



Total number of page faults 

Nustber of page faults for non resident pages 

Number of page faults fixed from reclaim li£ 

Number of demand zero page fatjilts 

Niimber of copy on modify page faults 

Peak virtual memory size 

Peak working set size 

Start time of process 

End time of process 

PeeOc page file usage 

Peak paged pool usage 

Peak non paged pool usage 

CPU and 10 accounting summary 



Cpu and 10 accounting summary 

An instance of this record exists in both the thread control block 

and in the process control block. Updates to the pcb version requires interlocked 

instructions . In the TCB version, only the execute io counters will have to be updated 
using interlocked instructions 



e$cpu_and_io_3ummary : RECORD 

cis_opu_oycle3 : large_integer; 



! Number of cycles used by the process or 



10 Accounting 

Request XC s are counted once. 

Each FPU that passes on an IKP (execute_io' s) must also record the transfer 

by incrementing the counter for its class of FPU 



cis reque3t_io count : integer; ! Number of request io' s 

ci3_execute_io_count : ABRAY[e$fpu_cla3a] OF integer; ! Number of execute io' s per fpu class 
END RECORD; 



Determines the granularity in the execute io count array 
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e$fpu_class : ( 



a$c_fpu_disk, 
e$c_fpu_tape, 
e$ c_f pu_tonninal , 
o$ c_f pu_network , 
s$c_fpu_gonoric 
); 



Quota and Resource Usage Data Structures 



e$quota_vector : AEEAY[e$quota_typ«a] OF integer; 



! Disk FPU's 

! Tape FPU' s 

! rerminal FPU' s 

! Network FPU's 

! Generic FPU's 



e$guota usage 
e$c[uota limits 
e$quota_type3 : 



e$quota_vector; 
: e$quota vector; 

( 
e$c_paging_file_quota, 
e$c_paged_pool_quota, 
e$c_nonpaged_pool_quota, 
e $ c_cpu_t ime_qu o t a 
); 



User Job, Process, and Thread Creation Records 



e$u3er_record : RECORD 

user_usemame : string (o$c_niax_U3er_naiae) ; 

user security_jprofile : a$security_profile; 

usor_per_user_limit3 : a$quota_liniit3; 

u3er_per_job_liinit3 : e$(3uota_lirtiit3; 

u3er_jper_jproce3s_limits : e$quota_limit3; 

user_thread_priority : k$coiiibinod_priority; 

user_thread_af£inity : k$affinity; 

user_aoce3a_re3trictions 
END RECORD; 



e$acce3s restrictions; 



User Name 

User Security Profile from Authorization Fi 

Per User Resource Limits 

Per Job Resource Limits 

Per Process Resource Limits 

Default Thread Priority 

Default Thread Affinity 

Users Access Restrictions 



e$job record : 
job_cla33 



RECORD 
e$jab class; 



Per job Resource limits. This value is used as the 
qual_limit3 value for the job object, and is deducted 
from the qtual_usage field of the jobs user object . 
A value of zero ( } in any one of fields means to use the 
corresponding value of the q_per_job_limit from the 
user structure 



job_per_job_limit3 
END RECORD; 



e$guota limits; 



e$process_reGord : RECORD 

proce33_3tatus_object : e$object_id; ! Object ID of processes status object 
proce33_image_name : string (e$c_max_image_name) ; ! Image niume for process being created 

Per Process Resource limits. This value is used as the 
qual_limits value for the process object, and is deducted 
from the qual_usage field of the owning job object. 
A value of zero() in any one of fields means to use the 
corresponding value of the q_per_process_limit from the 
user structure 



process_per_process_limits 
END RECORD; 



e$quota_limits; ! Resource limits for this process 



e$thread_record : RECORD 

thread_stack_size : integer; 
thread_jpriority : k$corobined_priority; 
thread_affinity : k$affirtity; 

END RECORD; 

Misceleneous Thread Creation Parameters 



If all then default 

initial thread priority if all then default 

complement of affinity If all then all processor 
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e$throad_eiiti:y_jpoiiit : PROCEDDBE (); 

k$a££inity : SET integer [0 . .k$c_h±gh_proce3sor_n'U]iiber] ; 

]c$conibined_priority : integer[0 . .k$c_highjpriority_level] ; 

k$ininor_priority : integer [ .. 3 ] ; 

e$job_claas ; (e$c_jc_invalid, 

e$c_je_network, 

e$c_ j c_inter active , 

e $ c_ j c_bat ch , 

e$c_jc_rsvdl , 

e$c_je_rsvd2, 

e$c_je_ravd3 , 

e $ c_ j c_r avd4 , 

e $ c_ j c_r avdS 

); 



! The tJaer Vxaible Proceas Control Region 
! 

e$proceaa_control_r6gion : RECORD 

pcr_image_naune : string (e$c_n!ax_image_name) ; 

pcr_total_nunibar_o£_threada : integer; 

pcr_nuiaber_running_threada : integer; 

pcr_objeot_id : e$object_id; 
duplicate o£ p_obj_id 

pcr_jprotected_data_hd : e$linked_li3t; 

per_data_block : POINTER anytype; 

pGr_data_block_length : integer; 

pcr_exit_handler3 : e$linked_li3t; 
END RECORD; 



! process image name 

! total nuznber o£ threads for this process 
! nTimber o£ running threads £or this procE 
! process object id - 

! List head of pretexted data 

t Initial process data or NIL 

! length rounded to quad in bytes of data 

! process level exit handlers 



The User Visible Thread Control Region 

!$thread_control_region : RECORD 

tcr_objeot_id ; e$object_id; ! Object ID o£ this thread 

tcr_stack_array : ABBAY[0..1] OF e$stack_repr63entation; ! tcr stack array 
tcr_ourrent_stack_index : integer [0. . 1] ; ! index of current stack 

tcr_pcr_pointer : POINTER e$proce33_control_region; ! Pointer to proceas control region 
tcr_handler_array : AREAY[k$processor_mode] OF e$vectored_handler3; ! vectored handlera for kemeZ 

! user mode 
tcr_exit_handlers : e$linked_li3t; ! Thread exit hsmdlers User mode only 

tcr_3tart_addreas : e$thread_entry_point; ! initial start address of thread 



Initial Thread Parameters 



tcr_data_block : POINTER ainytype; 
tcr data block length : integer; 
tcr_parameterl : POINTER anytype; 
tcr_parameter2 : POINTER anytype; 
LAYOUT 

tcr_object_id; 

tcr stack_array; 

t cr_curr ent_st ack_index ; 

t cr_pcr_poi nter ; 

tcr_handler_array; 

tcr exit handlers; 

tcr_start_address; 

tcr_data_block; 

tcr_dat a_block_length; 

tcr_parameterl; 

tcr_parameter2 ; 
END LAYOUT; 
END RECORD; 



Thread Environment Block User Mode R3 points to this 



Initial thread data or NIL 
Length rounded to quad in bytes 
Immediate parameter / or zero() 
Immediate parameter / or zero () 
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e$thread_envixoninent_block : BECOBS 

teb_heador : e$coinnion_teb_tcb_head«r; 
teb vm zone : Integer; 
tls_array_ad<ire33 : POINTER anytype; 
tl3_array_froe : integer; 
LAYOOT 

teb_header; 

teb_vm_zone; 

1 1 a_ar r ay_addr e s a ; 

tl3_array_f ree ; 
END lAYOUT; 
END RECORD; 



! common tieb/tcb header 

! thxead local vm zone 

! address of thread local storage control 

! byte offset of first unused tls control array si 



Misceleneous TCR Constructs 



e$vectored_handlers : RECORD 

primary_handler3 : e$linked_li3t; 
last_chance_h«uidlers : e$linked_list; 

END RECORD; 

e$stack_representation : RECORD 
initial_3p : POINTER anytype; 
staek_liniit : POINTER anytype; 
3tack_baae : POINTER auiytype; 

END RECORD; 



! Initial Value of Condition SP 
! Condition Stack Limit 
! Condition Stack Base 



Common TEB, TCB Header, R3 always points to this structure kernel mode, or user mode 



e$conimon_tebJtcb_header : RECORD 
ONION CASE * 

WHEN 1 THEN 

teb_length : integer; 
WHEN 2 THEN 

tcb_previous_mode : k$proces3or_mode; 
END UNION; 

tcr_addreas : POINTER e$thraad_control_region; 
LAYOOT 

ONION 

OVERLAY 

teb_length; 
OVERLAY 

t cb_previous_mode ; 
END ONION; 
t cr_addr e s 3 ; 
END LAYOOT; 
END RECORD; 



! When teb header first word is length 
byte length of teb 
When teb header first word is previous mode 
saved previous processor mode 

Pointer to TCR 



Thread performance data 



e$thread_perf_counter3 : RECORD 

tpc kernel ticks : integer; 

tpc_u3er_ticka : integer; 

tpc_preemption_switch : integer; 

tpc_voluntary_switch : integer; 

tpc guantiun ends : integer; 
END RECORD; 



Item Codes For User, Job, Process, and Thread Services 



A-7 



Executive Constants and Data Types 



e$ujpt_itom_codoa : ( o$c_ujpt_nil_code, 

e$c_job_count, 
o$c_job_ida, 
e$c_usemaino , 
a$c quota usage, 
o$G_u3er_lind.t3, 
e$c_job_limLta, 
o $c_proeosa_liniit a , 
e$c_thread_priority, 
e$c_thread_affinity, 
e$c_accesa_reatrictiona, 
e$c_user_id, 
e$c_proceaa_count , 
e$c_proceaa_ida, 
e$c_job_claaa, 
o$c_job_id, 
o$c_par«nt_id, 
e$c_3ub_proceas_count, 
e$c_3ub_proca3a_ida, 
e$c_thread_count , 
e$c_thread_ids, 
e$c_jproce3a_accounting, 
e$c_pcr_ba3e , 
e$c_protected_data, 
a$c_proce33_id, 
e$c_tcr_ba3e, 
e$c_throad_accounting, 
e$c_throad_parf _counters , 
e$ o_thread_innr_priority , 
e$c_thread_injr_priority, 
e$c_get_entire_object 

); 

Exit Status Object Data Types 

e$3tatu3_object_typo3 : ( e$c_3tatU3_procea3, 

e$c_statu3_thread ) ; 

o$exxt_status_aunimary : RECORD 

3tatus_bound_objoct_type : e$status_object_typea; ! Process or Thread 

3tatU3_bound_object_id : e$object_id; ! Object ID of object reporting ai 

statTi3_value : status; ! Exit Status 

stat-u3_string_pointer : POINTER varying_3tring(e$c_es_max_sti:ing) ; ! Pointer to exit status string 

END RECORD; 

Get Set information item codes for exit status objects 

e$exit status item codes : ( e$c_exit_statua_nil_code, 

e$c_3tatus_value, 
e$c status string, 
e$c_3tatu3_3tring_3et, 
e $ c_3 1 atu3_suiiimary 
); 

e$exit_handler_id : POINTER anytype; 

e$exit_handler_placement : { . -. 

e$c beginning_of_li3t, 
e$c_end_of_liat 

); 



A-8 



Executive Constants and Data Types 



^.7 Object Architecture Data Types 



All object creation object service routines take as a 
parameter 2in e$object_paraineters record. This record 
specifies the container that the object is to be created in, 
the name of the object, and the acl for the object. Any, or 
all fields can be defavilted to zero() in which case the object 
service routine chooses an appropriate default value. 

e$object_parainetera : RECORD 

object_container_id : e$object_id; 

name : varying_string (obj$c_meuc_object_name) ; 

acl : POINTER e$access_control_list; 
END RECORD; ~ 

! 

! Xtem codes used in the get information services for 

! object architecture defined objects like object containers, 

! container directories, and all object headers 

I 

e$object_item_code : ( 
e$c_acl, 

e$c_allocation_object_id, 
e$c_create_di3able, 
e$o_level, 

e$c_logical_name_liat, 
e$c mode, 
e$c name, 

e$c_nonpaged_pool_charge , 
e$c_object_containar_id, 
e$c_object count, 
e$c object id count, 
e$c_object_id_list, 
e$e_object_3tate, 
e$o_object_type_namo, 
e$c oid level, 

e$c_oid_objoct_container id, 
e $ c_oid_ob j e ct_id_type , 
e$c_otd_id, 
e$c_owner, 

a $ c_pagod_po o l_charge , 
e$c_pointer_count , 
6$c_principal_object_id, 
e $ c_wait abl e 

); 

representation of an object id 

e$object_id : QUADWORD; 

This data structure is used whenever a variable length list of object 
ids is required 

e$object_id_list (length : integer [1. . ] ) : RECORD 
CAPTtJRE length; 
last_valid_enfcry : integer; 
context : large integer; 

object_id : ARRAY [1. .length] OF e$object_id; 
lAYOUT 

length; 

la3t_valid_entry; 

context; 

object id; 
END LAYOUT; 
END RECORD; 
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A.8 Security Related Data Types 



e$aGce3a_coiitrol_li3t (ace_count : integer [0. .e$c_max_ace_count] ) : RECORD 
cap TURE aco_count ; 
VAEtraNTS CASE ace_count 
WHEN THEN 
NOTHING; 
WHEN OTHERS THEN 

ace : ARRAY [1. .ace_count] OF a$aoce3a_control_entry; 
END VARIANTS, - 

LayouT 

ace_count ; 

VARIANTS 

OVERLAY 

reserved : FILLER (longword, *) ; 
ace; 
END VARIANTS; 
END LAYODT; 
END RECORD; 

e$acces3_type : ( 

e$c_ganeral_acco3s_l , 
e$c_goneral_accaas_2 , 
e $ c_gene r al_acca a 3_3 , 
e$c_general_access_4 , 
e$c_genor al_acce 3a_5 , 
e$G_general_acce3a_6, 
e$G_general_acca33_7, 
e$c_general accesa 8, 
e$c_general_accesa_9, 
e$c_general_acceaa_10 , 
o$c_general_acceaa_ll , 
e$c general access 12, 
e$c_general_acceas_13, 
e $ c_gene r al_acce aa_l 4 , 
o$c_general_acce3s_15 , 
e $ c_general_acce a s_l 6 , 
e $ c_gener al_aoce a a_l 7 , 
e$ c_gener al_acce 3a_l 8 , 
e$c_general_accesa_19, 
e$c_generaL_acce3a 20, 
e$c_goneral acceaa 21, 
e$c_general_acce3a_22 , 
e$c_general_acce33_23 , 
e$c_generaL access 24, 
e$c_generaL accesa 25, 
e$c_general_acces3_2 6 , 
e$c general access 27, 
e$c_general_acces3_28 , 
e $ c_general_acce3a_2 9 , 
e$c general access 30, 
e$c_general accesa 31, 
e$c_general_acce33_32, 
e$G_apecif ic_accesa_l , 
e$G specific accesa 2, 
e $ G_spe ci f i c_acce3 3_3 , 
e$c specific access_4, 
e$c_speclf lc_aCGea3_5 , 
e$G_3peclflc_access_6, 
e$c specific access 7, 
e$c_3peclflc access 8, 
e$c_specific_accea3_9, 
e$c_3peci£ic_acces3_10, 
e$c_speclflc access 11, 
e$c_speciflc acceaa 12, 
e$c_speci£ic_acceaa_13 , 
e$c_apeci£lc acceaa 14, 
e$c_speGiflc_aGCesa_15, 
e$c specific access 16, 
eSc_3pecific access 17, 
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e$c specific access 18, 
e$c_specx£ic_accesa 19, 
o $c_speci £i c_acces s_2 , 
e$c_spoci f i c_acces s_21 , 
e$c_3pacifia_accesa_22, 
e$c_apeoif ic_acces3_23 , 
e$c_apecific_acce3a_24, 
a$c specific acceaa 25, 
e $ c_speGi f i c_acce3 3_2 6 , 
e $ c_3peci f i c_acco a s_2 7 , 
e$c_specif ic_accass_28 , 
o$G_specific_acce8s_29, 
e$c_3peci£ic_access_30, 
e$c specific access 31, 
o$c_3pecific_acce33_32 

); 

e$identi£ier : longword; 

e$inip_idantifier_option : ( 
e$c_cliant_idontifier3, 
e$c_union identifiecs 

); 

e$aecurity event : ( 

e$c_acl_audit 3ecurity_event 

); 

e$acce33_ace_flag : ( 

«$c_nontenninal_ace_flag 
); 

e$ace_flag : ( 

e$c_de f ault_ace_f 1 ag, 
e$c nopropagate ace flag 

); 

e$ace type : ( ' 

e$c_aecoss_ace, 

e$c_audit_aco 

); 

e$audit_aco_flag ; ( 

e$c success ace flag, 
e$c failure ace flag, 
e$c_alarni_ace_flag 
); 

e$access_control_entry : RECORD 

ace_type : e$ace_type [..] SIZE (byte) ; 
ace_flag3 : SET e$aca_flag [..] SIZE (byte); 
reserved : byte_data (2) ; 
UNION CASE * 

WHEN 1 THEN ! Access ACE specific 

access_flag3 : SET e$acces3_aee_£lag [..] SIZE (byte) ; 

access_identifier_count : integer [1. .e$c_max_ace_identifier_count] SIZE (byte); 
access_access_allowed : SET e$access_type [ . . ] ; 

acce3s_identifier : ARRAY [1 . .e$c_max_ace_identifier_count] OF e$identifier; 
WHEN 2 THEN ! Audit ACE specific 

audit_flags : SET e$audit_ace_flag [..] SIZE (byte); 
audit_acces3_monitored : SET e$acceas_type [ . . ] ; 
audit_name : vaEying_3tring (o$c_niaix_audit_name) ; 
END UNION; 
END RECORD; 
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A.9 Condition Handling Data Types 



o$condition_r«cord_pointer : POINTER e$condition_rocord; 
e$mechani3in_record_pointor : POINTER e$mechaniam_record; 

e$conditlon_handler : PROCEDI3RE ( 

IN condition_record : e$eondition_r«cord_pointer; 
IN m©chani3iii_record : e$niachani3m_rocord_jpointer; 
) RETURNS status; 

e$condition_handler_id : POINTER anytype; 

e$condition_record( argiainent_n\jjnber : integer [ 0.. ] ) : RECORD 
CAPTURE arguinent_niiiiiber; 
condition_name : status; 

condition_flags : SET e$condition_flag3 [..]/ 
conditioii_list : e$condition_record_pointor; 
processor_status : arch$procesaor_status; 
aondition_addreaa : a$instruction_pointer; 

argtunenta : ARRAY [ 1. .argument number ] OF e$arguinent descriptor; 
lAYOUT ~ 

condition_name ; 

oondition_flag3; 

oondition_liat ; 

proce33or_atatU3; 

condition_addres3 ; 

unused : FILLER ( longword, 1 ) ; 

arguinent_nuniber; 

arguments; 
END LAYOUT; 
END RECORD; 

e$mechanism record : RECORD 

3tack_valid : boolean [ . . ] SIZE ( longword ) ; 
e3tabli3her_fp : e$frame_pointer; 
UNION CASE *. 

WHEN 1 THEN 

retum_3tatus : status; 
WHEN 2 THEN 

fir3t_return_register : arch$rogi3ter; 
second_raturn_regi3ter : arch$rogi3ter; 
END UNION; 

LAYOUT 

stack valid; 
establisher £p; 
UNION 

OVERLAY 

return_st atus ; 
OVERLAY 

fir3t_return_regi3ter; 
3econd_return_r6gister; 
END UNION; 
END LAYOUT; 
END RECORD; 

e$frame_pointer : POINTER anytype; 

arch$proces3or_atatua : integer; ! dummy definition 
arch$regi3ter : longword; 

e$in3tructibh_pointer : POINTER arch$instruction; 
arch$in3truction : integer; ! dummy definition 
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e$arc[unien1:_descriptor : RECORD 
ONION CASE * 

WHEN 1 THEN 

extent : integer; 
ptr : POINTER anytype; 
HHEN 2 THEN 

immediate : integer; 
WHEN 3 THEN 

large_iimnediate : quadword; 
END ONION; 

class : integer [0. .255] SIZE (byte); 
datatype : integer [0..2S5] SIZE (byte) ; 
size : integer; 
lAYODT 

ONION 

OVERLAY 

extent, 

ptr; 

OVERLAY 

immediate; 
OVERLAY 

1 arge_immBdi at e ; 
END ONION; 
class; 

sbzl : FILLER (byte, 2); 
datatype ; 
size; 
END LAYOOT; 
END RECORD; 

e$condition_flag3 : ( 

e$c_condition_unwinding, 
. e$c_Gondition_noncontinuablo, 
e$c_condition_exit_unwind, 
e$c_condition_during_ast , 
e$c condition_aaync 

); ~ 
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os$translateJogical_name • 2-6 
os$translate_object_name • 1-20 
os$unlock_pages_from_nnemory • 8-1 7 
os$unlock_pages_working_set • 8-1 8 



os$update_mapped_section • 8-1 9 
os$verify_priv_operation • 1 0-1 6 
os$wait_multiple • 3-2 
os$wait_single • 3-4 
os$wake_process • 7-43 
os$wake_thread • 7-44 
os$zero_to_end_of_user_stack • 8-21 



Process architecture data types* Ar-4 



Security related data types ■ A-9 
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